$G in practice

Development Environment

The graphics group has developed a system over many years that allows easy development of a large, shared base of software. We give the whole thing the nickname $G ("dollar gee"), named after the environment variable that represents the root of the source tree.

There source code our group has created is modified and backed up through a source control system called CVS (Concurrent Versioning System). You must have CVS set up properly in order to develop with our shared codebase.

Source control works by allowing an individual user to make structured copies of the master versions of files (this process is called "checking out" the files). The user then modifies his or her personal copies of the files, and then "checks in" the changes once they're certain that the code compiles and runs properly. The location where a user modifies a personal copy of shared code is called a "sandbox", because it is in some sense walled off from the master copy: destructive changes to the code in the sandbox do not affect the master copy, provided the user doesn't check them in.

Environment variables are used to configure the development environment. Visit this page for general instructions for Setting Environment Variables and using them. The instructions in the remainder of this section require that you know how to set up environment variables. For Windows the instructions use the native Windows (cmd.exe) command shell. Unix command examples should work on most shells.

Even if you intend to work on Windows you should set up your sandbox at Brown using Linux. The instructions will include Windows specific instructions when applicable. Explicit procedures for setting up a remote Windows system (like your laptop) are not yet in place. If you are familiar with setting up Windows development environments you should be able to adapt these procedures.

Here's a description of the directories you will find under /map/gfx0/:

• data: A directory for large datasets.

• users: Space for students to set up sandboxes.

• tools/linux/import: Pre-installed third party software.

• tools/linux/install_linux: Shared copies of pre-built Linux projects.

• tools/linux/install_WIN32: Shared copies of pre-built Windows projects.

• cvsroot: The CVS repository. The files in here are only for administrators to access. Students should only access the repository through CVS commands.

Within the CVS repository the primary directories are:

• import: Downloaded kits for third party software.

• common: Software used by multiple projects.

• project: Project software.

Access to CVS

The CVS repository is accessed by setting the 'CVSROOT variable. Once set you will be able to checkout code and make updates to the repository.

On Unix set CVSROOT to: /map/gfx0/cvsroot/

On Windows set CVSROOT to: Y:\map\gfx0\cvsroot\

CAUTION: The free versions of CVS we've tried do not work reliably on Windows. Unless you carefully check your work you should perform CVS operations on Unix. It is generally safe to do a read-only check out of software from CVS on Windows.

The CVS repository has the golden copies of our software. It is a high valued item so you need to use caution whenever you modify it. It is important to understand how CVS works and what effects CVS command have. If you are new to CVS there are many tutorials online to help you get started. Note that deleting or renaming directories in the CVS repository needs to be done by an administrator.

One page cheat sheet for CVS:  http://www.bravegnu.org/cvscheat/cvscheat.pdf

Creating a Development Sandbox

Your sandbox is the area where you work. It can be any directory, but the area /map/gfx0/users/<Login Id> is set aside for students in the graphics group. Create a directory there to work in or if you'd like also create a subdirectory to work in. To create your own sandbox, do the following (the ">" just indicates the beginning of each command):

> mkdir -p /map/gfx0/users/$USER             #Establish your work area.
> cd  /map/gfx0/users/$USER
> mkdir -p  <subdirectory>/<sandbox>         #Optionally create a $G work area.

After setting everything up your sandbox will have several top level directories. The common/ directory contains software shared by projects and the project/ directory contains student applications. There are two other directories of interest. One is the import/ directory which is where third party software is installed. The other is the install_linux/ or install_WIN32/ directory. This is where software that you build is installed when you perform a "make install". All of these directories can be rearranged to suite your needs. If you are just getting started just create them all at the top level of your sandbox.

The common/ directory has the build make files and shared programs and libraries written at Brown. You only need the common/build/make/ directory to develop programs, but since you probably will eventually want other common code just check the whole directory out.

> cd   <Sandbox>            # Go into your sandbox directory.
> cvs  co  common           # Get all the common software.

Next create the remaining top level directories that you will populate in subsequent steps.

> mkdir project
> mkdir import
> mkdir install_linux
> mkdir install_WIN32       # Optional if you only use Linux.

Setting Environment Variables

There are several environment variables to set up. You can set these up in your login scripts along with the setting for CVSROOT.

GARCH: Designate the platform architecture.

GARCH = WIN32           # Use this setting on Windows.
GARCH = linux           # Use this setting on Linux.

G: This is used to access the G Build system and is set to the location of the common/ directory. By default it is also used to access the import/ directory. If your sandbox is at the top of your users' directory then set:

G = /map/gfx0/users/<login>

G_IMPORT: You can optionally set this to designate an import/ directory. This lets you put it wherever you want and also switch between multiple import directories. For example, if you wanted to try the public imports instead of those in your sandbox then you could set it to: /map/gfx0/tools/linux/import

GROOT: This variable is used to access these directories:

 $GROOT/data          # Contains large data sets.
 $GROOT/users         # Work areas for end users.

GROOT = /map/gfx0

GTO: This is the location of the install directories. Usually you will want to keep them at the top of your sandbox then it will be the same as $G.

GTO = $G

G_COMPILER: Set to the compiler you want to work with. You might need to change this depending on project requirements. Supported settings are:

               Linux                             Windows

          gcc2 - gcc version 2.95            cl6 - Microsoft Studio version 6      
          gcc3 - gcc version 3.4             cl8 - Microsoft Studio version 8 (2005)
          gcc4 - gcc version 4.1             cl9 - Microsoft Studio version 9 (2008)

If you want to explicitly designate a compiler visit this page with a more detailed description of G_COMPILER.

PATH: Only on Windows does this needs to be set in order to access the Unix utilities for Windows. A few Unix utilities are needed to build projects. You can check these out of CVS from Linux with:

> cd   <Sandbox>
> cvs  co  import/make        # Check out the utilities on a Linux computer.
            :
> ls /map/gfx0/users/$USER/import/make/g.utility_1.0/
CVS/         cp.exe*    echo.exe*   libiconv2.dll  make.exe*   mkdir_gnu.exe*
READ_ME.txt  diff.exe*  false.exe*  libintl3.dll   mkdir.exe*  rm.exe*

Now switch to the Windows computer. You will need to add the path to g.utility_1.0\ to the front of your Windows PATH environment variable. On Windows the path is "Y:\map\gfx0\users\<User ID>\import\make\g.utility_1.0" After it is set verify that you can run these utilities from the command shell of your choosing. The native Windows command shell is cmd.exe.

Verify You Can Build Software

• Build on Linux

Try a simple build to see that everything is properly set up.

> cd  <Sandbox>/common/utility
> make  all                 # Build the utilities.
> make install              # Install the utilities.

This should populate the install directory. Take a look with:

> ls  <Sandbox>/install_linux/*/*

• Build on Windows

If you've not already done so, set your Windows environment variables according to the section "Setting Environment Variables". To see if you can build software run the 'cmd.exe' shell and try:

> cd/d  <Sandbox>\common\utility
> make  all                                         # Build utilities on Windows.
> make  install                                     # Install them to:  install_WIN32\

Finally inspect <Sandbox>\install_WIN32 to ensure it was properly populated.