art's abode

art.csoft.net

Archive for the ‘guide’ tag

Compiling, Using and Developing on Microsoft Singularity

with 2 comments

I’ll be adding more to this post quasi-frequently.

This post is based on the Singularity RDK 2.0 images and source, which are available here: http://www.codeplex.com/singularity.

Singularity can be run fairly easily. You can also roll your own, and compile Singularity from source.

What you will need:

  • Singularity RDK 2.0 ISO image.
  • Singularity RDK 2.0 sources: if you wish to compile from source.
  • A machine: physical, or virtual*.

* I’ve used Microsoft Virtual PC Beta on a Windows 7 7100 x64 host machine. I’m told it works for Virtual PC 2007. I was unable to get it working with VMWare Server 2.0.

Running Singularity

  • Download the ISO image.
  • Burn it to a CD, or save to a location mountable for your VM.
  • Boot the ISO.

You now should have Singularity running, using the default build. If you just wanted to look gangsta–mission accomplished, take your screenshots and begin bragging to on web forums:

singularity_vm

However, if you want to explore the OS (such as it is), read on.

What the Hell is This, Min?

OK, don’t panic. Looks daunting, I know. Acquaint yourself with this little gem, for starters: “Singularity_RDK_2.0_Source\docs\Design Notes\SDN87 RDK Applications Guide.pdf“. It is from the RDK 2.0 source download, and will give you a good idea of how to use Singularity commands.

Some commands:

  • help: display all commands.
  • dir.
  • start.
  • ipconfig @show: display status of all NICs.
  • dns @show: display DNS settings.
  • seditor: an EDLIN-like editor.
  • sc @show: show status of all services.
  • tasklist: show list of all tasks.
  • jobs: show a list of all jobs.
  • fg n: foreground job number n. Use ^C to quit the job.
  • shutdown.

Backgrounding:

Use & to run programs in the background. You can ^Z halt processes, then use bg n to background it.

Compiling From Source

The source comes with a PDF: Building and Running Singularity RDK 2.0.pdf. Read it.

Essentially you follow the instructions as given in that document:

  • Get the prerequisites for the environment.
  • Run “configure.cmd”.
  • Delete/rename the directory “Singularity_RDK_2.0_Source\base.obj”, if it exists.
  • Run the “Singularity RDK 2.0” desktop icon which will bring up a command line prepped for building Singularity or debugging it.
  • At the prompt, type as below to build Singularity World distro:
    …\base> msb Distro\World.proj
  • If it dies saying it couldn’t find a directory within “Singularity_RDK_2.0_Source\base.obj\MSBuildLogs\6\…”, don’t worry. Go into that MSBuildLogs directory and create the 6 directory. Now the MSBuild should work.

image

image

  • You can find generated ISO image for your build in “Singularity_RDK_2.0_Source\base.obj\Distros”.

If you modify any .scripts, for example, you may wish to recompile to include the modifications on an ISO; you just repeat the above process after making your changes to “C:\src\Singularity_RDK_2.0_Source\base\Distro\Scripts\startup.script”, for example.

As a rough benchmark, it takes me 10-15 minutes to build World on a quad core with 8 GB memory.

Networking

Aye, it works.

If you’re ultra-lazy, just do the following:

Singularity>ipconfig @dhcp /dev/nic0 start

This should get you going with DHCP. It’ll poll the DHCP server for DNS servers too.

You can set a static ip thusly:

Singularity>ipconfig /dev/nic0 192.168.1.99 255.255.255.0 192.168.1.1

The format is ipconfig <device> <ip> <netmask> <gateway>.

Remember that if you set a static IP using ipconfig, you will need to tell Singularity which DNS servers to use, check the dns command.

Enabling VESA

Edit the file “Singularity_RDK_2.0_Source\base\Distro\LegacyPCDistro.xml“.

Enable the line:

<driver name=”S3Trio64″ />

Recompile, and you’ve got VESA.

image

I prefer without VESA as it has a handy thread statusbar at the top of the blue screen, which is apparently gone in VESA mode. Pity.

FAT drives

For FAT support open your Distro build file (i.e., “Singularity_RDK_2.0_Source\base\Distro\World.proj“), add the following line:

<Application Include=”$(SINGULARITY_ROOT\Services\Fat\Control\FatControl.csproj”/>

Recompile, and you’ve got FAT support.

Make sure you’ve partitioned your FAT drive beforehand. You should be able to see it listed in the /dev tree.

Now, you can @format, @mount and @unmount your FAT drive using fatcontrol.

image

.script files and customizing startup.script

If you are serious about using Singularity, you will likely want to modify your init/startup.script. The best way to do this is to edit this on your host machine, then msb.

Note that you will have to put ‘single quotes’ around all arguments. For example, the shell command hostname -n=paddington (this changes the machine’s hostname to “paddington”) would be put in startup.script as:

hostname ‘-n=paddington’

There are plenty of examples in the RDK for you to get started with. Here is Singularity booting up, setting hostname, a DHCP connection, a static IP, and mounting a FAT drive:

image

Jobs

If you try to reboot or shutdown while there are jobs, Singularity will freeze. Nice. For now, just remember to kill all your jobs by foregrounding them (jobs, fg n, ^C).

Developing in Singularity

Read this thread which discusses the best way to develop for Singularity: http://singularity.codeplex.com/Thread/View.aspx?ThreadId=23669.

A quote:

copy an existing project like …\base\Applications\Hello\

to …\base\Applications\MyProj\

cd …\base\Applications\MyProj\

rename .cs and .csproj files, edit them for content.

msb MyProj.csproj (until it compiles)

back to …\base

edit distro\tiny.proj and add a line for your app

<Application Include=”$(SINGULARITY_ROOT\Applications\MyProj\MyProj.proj”/>

msb distro\tiny.proj

In general, I’ve found the process to be fairly straightforward, once you get the hang of it. I would recommend you compile a World distro, and keep the base.obj directory. Now, go into the base directory, and edit your sources/files.

The next time you msb the distro, it will only recompile/update the changed files. This is a pretty quick way to edit the scripts, and not too long if you are coding.

As a benchmark, it takes less than a minute for me to msb world, if I’ve made changes to 1 or 2 code projects within the source tree:

image

Debugging with WinDbg

Create a named pipe to COM2, and you can call the debugger using “dbg.cmd /pipe”.

image

Now, when you start up your Singularity VM, it will automatically output the debug to WinDbg:

image

Caveats

  • Some example applications are buggy/not working.
  • US keyboard layout only? I couldn’t find a way to change this anywhere in the source.
  • Couldn’t get the /dev/audio device with Virtual PC Beta.

Demo Server

I have set up a demo Singularity web server, details here.

Written by art

June 3rd, 2009 at 6:24 pm