Automatic Start-up and Configuration

Normally, running a Chromium configuration involves starting the mothership then one or more server nodes (crserver) and application nodes (crappfaker). With the auto-start / auto-config feature you can simply run an OpenGL program normally and have it run on Chromium.

Auto-Start

The node.AutoStart() function allows you to execute an arbitrary shell command in order to spawn the Chromium crserver and crappfaker programs. This saves you from having to manually starting the programs yourself.

To start, let's define two strings with some environment variables and the name of the program to run:

env = "LD_LIBRARY_PATH=" + crlibdir
prog = crbindir + "/crserver"

Now, here's an example of how to autmatically start a crserver on a remote host named "mars" using rsh:

node.AutoStart( [ "/usr/bin/rsh", "mars",
                  "/bin/sh -c '" + env + " " + prog + "'" ] )

Here's an example of how to autmatically start a crserver on the local host just using sh:

node.AutoStart( ["/bin/sh", "-c", env + " " + prog] )

To start the crappfaker instead of crserver, just change the prog assignment above.

Basically, the AutoStart() function takes a list of command line arguments which are passed to the Python os.spawnv() function.

We use /bin/sh (the Bourne shell) to be sure that the environment variables will be interpreted correctly. You may have to do some tinkering to make things work correctly on your system. Some things to check:

• Manually check that rsh or sh works without having to type in a password.
• Check where sh and rsh live in your filesystem and set the paths accordingly.
• Add extra environment vars as needed, such as CRMOTHERSHIP, if they're not set in your .bashrc file.
• To debug things, try typing the rsh or sh commands in a terminal window and see what happens (instead of using AutoStart right away).

Auto-Config

Auto-Config is a feature that automatically starts the mothership when you run an OpenGL program. In turn, the mothership can automatically start all the crappfaker and crserver processes (as described above). The end result is that users can run their OpenGL programs in the normal manner and automatically use Chromium.

This example assumes that Chromium is located in /usr/local/Chromium-x.y. Adjust these instructions accordingly if you have Chromium installed elsewhere.

The following steps need to be taken:

1. (For Unix/Linux) Use libcrfaker.so instead of libGL.so

We have to trick the OpenGL application into using the crfaker library instead of the normal OpenGL library. One solution is to create symbolic links from libcrfaker.so to libGL.so and libGL.so.1 and then use LD_LIBRARY_PATH to tell the application where to find the library. For example:

   cd /usr/local/Chromium-x.y/cr/lib/Linux
   ln -s libcrfaker.so libGL.so
   ln -s libcrfaker.so libGL.so.1
   setenv LD_LIBRARY_PATH /usr/local/Chromium-x.y/cr/lib/Linux

1. (For Microsoft Windows) Use libcrfaker.dll instead of opengl32.dll

We have to trick the OpenGL application into using the crfaker library instead of the normal OpenGL library. One solution is to copy the libcrfaker.dll to opengl32.dll and then use the PATH environment variable to tell the application where to find the library. This will ensure that the new opengl32.dll will be picked up before the system's version.

   cd c:\Chromium-x.y\cr\bin\WIN_NT
   copy libcrfaker.dll opengl32.dll
   set PATH=c:\Chromium-x.y\cr\bin\WIN_NT;....

2. Make a configuration file

A good way to make a configuration file is with the graphical configuration tool. You might make, for example, a tilesort configuration.

Make sure your configuration:

• Sets the Automatically Start Servers option (from the Mothership / Options menu).
• Sets the System GL Path option for the render SPUs so that the real OpenGL library is found.
• Do not set the Command option for the application node (from the Node / App Node Options menu).

Save your configuration to a file such as /usr/local/Chromium-x.y/cr/mothership/configs/myconfig.conf

XXX -temporary

For the time being, you may have to edit your configuration file and specify the full path to the Chromium server's python directory:

   sys.path.append( "/usr/local/Chromium-x.y/cr/mothership/server" )

Otherwise, the configuration script may not be able to find the mothership.py file.

3. Set up the .crconfigs file

The .crconfigs file is expected to be in your home directory (i.e. at /home/joe/.crconfigs). If it's not found there, Chromium will look in the current directory when you start your application.

The .crconfigs file maps program names to configuration names. Each line of the file is of the format:

program configuration

Here's an example:

   atlantis  /usr/local/Chromium-x.y/cr/mothership/configs/myconfig.conf
   city      /usr/local/Chromium-x.y/cr/mothership/configs/tilecity.conf -r1 -c2
   *         /usr/local/Chromium-x.y/cr/mothership/configs/default.conf %p

This example specifies configuration files for the atlantis and city programs.

In the case of the city configuration, two optional command line arguments are given to the tilecity script to set the mural rows and columns.

The * (asterisk) entry denotes a default to use when there is no other match.

The %p sequence will be replaced by the program name. If %d is present, it will be replaced by the current working directory. if %m is present, it will be replaced by a a randomly chosen mothership port number. The spawned mothership will listen on that port.

4. The CR_CONFIG_PATH and CR_CONFIG environment variables

If the CR_CONFIG_PATH environment variable is set, it will provide an alternate file to look in for configuration. The file contents are identical to that in .crconfigs. It is merely an alternate way of specifying the location. Here's an example:

setenv CR_CONFIG_PATH "/tmp/autostart.conf"

If the CR_CONFIG environment variable is set, the .crconfigs file is not processed and no matching for program names is done. Instead, the contents of the CR_CONFIG variable are used instead to identify which mothership configuration file is to be used. The same syntax is used as for the configuration section of a line in the .crconfigs file. Here's an example:

setenv CR_CONFIG
"/usr/local/Chromium-x.y/cr/mothership/configs/tilecity.conf -r1 -c2"

Run it!

At this point running a program, such as city, should cause everything to start automatically. Here's what happens:

• The application (effectively linked to libcrfaker.so instead of libGL.so) will make a GLX call which initialized the faker library.
• The faker library will try to contact the mothership, and fail (since it's not running).
• The faker library will look for the CR_CONFIG environment variable or lookup the program name in the .crconfigs file.
• The faker will now have the name of a configuration (possibly with command line arguments).
• The faker will try to spawn (fork/exec) the mothership, specifying the configuration and command line arguments.
• The mothership will start and create a thread that will spawn the crserver nodes. The servers will load their SPUs.
• The faker will contact the mothership and load its SPUs.
• Chromium will now be running.

Trouble shooting

Here are some things to check if this doesn't work:

• (Unix/Linux only) Run ldd programname and verify that you're linked against the faker library. You should see something like this:

  libGL.so => /usr/local/Chromium-x.y/cr/lib/Linux/libGL.so (0x4010b000)

  /usr/local/Chromium-x.y/cr/lib/Linux/libGL.so should be a symlink to libcrfaker.so
• (Microsoft Windows only) Check that the 'python.exe' application is within the system PATH if crSpawn fails. The easiest way to check this is open a 'cmd' prompt and type 'python' and hit return. If Python doesn't start - check your setup.
• Examine the output of the crfaker to see if your configuration is being found:

      CR Debug(foo:26248): Spawning mothership with argv:
      CR Debug(foo:26248): argv[0] = 'python'
      CR Debug(foo:26248): argv[1] = '/usr/local/Chromium-x.y/cr/mothership/tools/tilecity.conf'
      CR Debug(foo:26248): argv[2] = '-r1'
      CR Debug(foo:26248): argv[3] = '-c2'
  

• Check that your configuration file is able to find the mothership.py file; look for sys.path.append() lines.
• If the render servers aren't starting, make sure the auto_start option is set.
• Make sure there aren't any other mothership instances already running by checking the output of running ps -a or ps -e.