CMX (CMT, eXtended) is an extended version of CMT, developed in Perl and shell by Anthony Waite of SLAC's FSW group. It allows CMT to handle "projects", cross-compilation to multiple targets, code distribution, etc. With the assistance of CVS, Doxygen, GCC, and Graphviz, CMX maintains code archives, builds binaries, and produces a variety of online documentation.

CMX is a substantial system, with lots of options. The best source for detailed information (nay, the source of this web page) is the CMX Manual (a Traveler document, indexed under DAQ:CMX). Unless you're in a blinding hurry to get started, your best plan would be to download and/or print the manual and spend an hour or so perusing it.

Oh, still here? OK, we'll try to get you started and give you a useful "crib sheet", but don't be surprised if we gloss over a few points. And do try to get around to reading the manual at some point.

Getting Started

CMX relies on some rather complex shell trickery (e.g., complex aliases), so be sure to invoke your CMX commands from one of the supported shells (currently, bash and tcsh). The full path name for your default shell is stored in $SHELL:

    % echo $SHELL
    /bin/tcsh
     

If the reported path name doesn't end in either "/bash" or "/tcsh", you'll have to do one of two things: change your default shell or explicitly invoke a supported shell. Don't even think about porting CMX to some other shell!

Note: On BSDish and Linux machines, the chsh command will let you change your default shell. This command isn't present on Solaris, BTW. The SLAC Computing Services (SCS) administrators say:

You send email to unix-admin with the shell that you wish to change to. This will change your default shell on all the public machines at SLAC, both Solaris and Linux. You should note, however, that we really only support tcsh. Other shells are available, but you're on your own as to appropriate startup scripts.

For simplicity, we'll take much the same tack in the rest of this tutorial. If you're using bash, you'll have to make the appropriate mental conversions. Now, let's make sure that your shell environment knows about CMX:

    % which cmx
    cmx:     aliased to source ${CMX_I_CMX}/cmt/cmx_execute.csh !*
    % printenv | grep CMX_
    CMX_C_SITE=slac
    CMX_C_CDB=/afs/slac.stanford.edu/g/glast/flight/DAQ/source/CMX/CDB
    CMX_C_DOXYGEN=/afs/slac.stanford.edu/www/exp/glast/flight/doxygen
    CMX_C_DOXYURL=http://www.slac.stanford.edu/exp/glast/flight/doxygen
    CMX_I_CMX=/afs/slac.stanford.edu/g/glast/flight/DAQ/source/CMX/V2-0-6
     

If the answers you get don't match the above (disregarding shell- and site-specific variations), make sure that you are using the (appropriate) CMX setup script. Under tcsh, your .cshrc code might look like this:

    setenv GLASTROOT   /afs/slac.stanford.edu/g/glast
    source ${GLASTROOT}/flight/scripts/group.cshrc
     

The CMX "Help" Facility

Once CMX is available, you will have access to its hierarchial "help" facility. This is particularly useful if you have forgotten the name or format of an option, but it's also a quick way to familiarize yourself with CMX's capabilities:

    % cmx help

        add        Add a file to a package (CVS cover command)
        build      Build a CMX package
        ...

    % cmx help add

        cmx add <package> <files>

        <package>  Package name
        <files>    Comma delimited list of files (package relative)
     

Development "Playpens"

Developers need private areas (sometimes called "playpens") in which they can make changes, try things out, etc. At the same time, they need to be able to use stable versions of routines that they're not working on. Collectively, this allows a group of developers to move forward on assorted fronts, while staying out of each others' way.

CMX deals very nicely with these sorts of problems, allowing developers to concentrate on the work at hand. Let's assume that you need to work on the MSG Package, which is part of the DAQ Project. Here is a sequence of commands that you might use to get started:

    % cd 
    % mkdir glast 
    % cmx start
    % cmx create project FixMSG glast
    % find glast/FixMSG -print 
    glast/FixMSG
    glast/FixMSG/source
    glast/FixMSG/binary
     

The project name you select for the playpen (e.g., FixMSG) is quite arbitrary. In particular, it does not need to be tied to any "real" Project or Package name. It should, however, indicate the purpose of the playpen (to reduce confusion, later on...). Note also that you can have several playpens, containing some or all of the same packages. Keeping this straight is your responsibility.

Note: Although we used the "cmx start" command in this example, you may not want to bother with it. The first CMX command issued in a session will do an implicit "cmx start", if need be. It will, however, notify you of this fact by saying "CMX: Setting up the CMX environment".

Now, let's bring in a snapshot of the current production version of MSG and try building the binaries:

    % cmx fetch MSG --test=glast/FixMSG
    ... lots of CVS messages ...
    Creating setup scripts.
    Creating cleanup scripts.
    % cmx build MSG
    CMX: Requested branch differs from environment
     

Hmmmm. Although "cmx fetch ..." worked, "cmx build" didn't. The reason has to do with CMX's handling of defaults. The version defaults to "public production", but the "cmx build" command defaults to "--test". This is a conflict, so CMX issues a nastygram and gives up.

To go forward, you must tell CMX to record glast/FixMSG as a test branch of MSG (and use this branch for builds). You can then reissue the build command, successfully:

    % cmx set branch MSG --test=glast/FixMSG
    % cmx build MSG
    ...
     

In addition, because CMX has recorded the absolute location of the project files, you can move around in the directory tree, edit files, and still issue build commands:

    % cd glast/FixMSG/source/MSG/test/src
    % vi M2S_msgs.c
    ...
    % cmx build MSG
    ...
     

Finally, it's worth noting that CMX will use your test binaries, along with (but in preference to) any production binaries that might be needed. Because the system is based on "shareables" (aka DLLs), no explicit linking has to be done. Instead, the binaries are linked dynamically, according to a set of image-activation "resolution rules".

In summary, CMX has taken care of a large number of details, leaving you free to edit, build, test, and document your code. Because all of your work is being done in a private playpen, other development effort can proceed using production versions of the code you're working on.

Moving Code into Production

When you think you have most of the bugs out of your code, you may want to let it be tried out. This is a bit of an involved process, but CMX takes care of most of the grunt work. You need to "commit" your changes in CMX's captive CVS repository, update the public development branch of the package, tell CMX that you want to work with the development branch of MSG, and finally, build a development version of MSG:

    % cmx commit     MSG
    % cmx update     MSG --development
    % cmx set branch MSG --development
    % cmx build      MSG --development
    ...
     

Now would be a good time for you to inform your cohorts that there's a new "development" version of MSG. They can access this version by setting the MSG package to the development branch in their own environments. If your code survives their abuse, you can consider moving it to full production status. Be a bit cautious in doing this; moving broken code into production is not likely to increase your standing with your fellow developers!

That said, the actual process is quite simple. You must declare a new version "tag" in the CVS repository, fetch the code from the repository to the public production space, tell CMX that you want to work with the new branch, rebuild the package (for all possible target environments), and declare the result as the official production version. If MSG's new version number is V2-0-1, the commands would look like:

    % cmx create version MSG --version=V2-0-1
    % cmx fetch          MSG --version=V2-0-1 --production
    % cmx set branch     MSG --version=V2-0-1
    % cmx build          MSG --version=V2-0-1 --all
    ...
    % cmx set production MSG --version=V2-0-1 --global
     

Creating a new Package

Creating a new CMX package isn't difficult; here's a quick example:

    % cd
    % cmx create project FooDir glast
    % cmx create package FOO    glast/FooDir
     

Although we could have reused an existing private project, we have chosen to create a new one ("FooDir"). We then create a package ("FOO") which we can populate with code. Note that we went back to our home directory first. This saves us the trouble of fully qualifying directory names such as "glast" and "glast/FooDir".

Before we can build the code, however, we will need to edit the "requirements" file (located at glast/FooDir/source/FOO/test/cmt/requirements). The file contains numerous comments and is designed to be used as a template, so this process is relatively painless. If you get confused, try looking at a "real" requirements file.

After editing, building, testing, and documenting your code, you will once again feel brave enough to submit it to your fellow developers for testing. Before you can do this, however, you will need to declare FOO's official Project. After all, the FooDir Project is just a "playpen".

By consultation with Those Who Must Be Obeyed, you determine that FOO's will reside in the XYZ Project. No problem; just issue the following command:

    % cmx import FOO XYZ
     

As noted in the "A Quick User Walkthrough" in the CMX Manual, this command performs some really intricate (and potentially dangerous) operations. Fortunately, CMX is pretty conservative about checking for problems, so you aren't likely to hurt anything. Still, try not to issue this command incorrectly!

In any event, you can now do a development build and follow the steps leading to a production release. Enjoy...