GoGui: Functions

Overview. GoGui is a GUI-based build tool for use with SConscript builds. Effective use of GoGui depends on:

• Access to the cvs repository.
• Access to the external libraries.
• A working installation of SCons.

Assumptions

It is assumed that you are familiar with:

• using RMViewer to determine the container package you are interested in.

It is also assumed that you are already familiar with the procedures described in:

• GoGui: Workspace Scenarios.
• GoGui: Initial Setup — SLAC Central Linux.
• GoGui: Initial Setup — Desktop Installations.

Note: While not specifically described in any of the above, it should be mentioned that on SLAC Central Linux there are essentially two methods of performing a build:

"Build in place", i.e., the use of an existing build in the Builds directory (identified when you Set base path...) with the output saved to your work directory (where you have write access, and which is identified when you Set supersede path...). (See Implementing Scenario 1.) Copy a Release Manager (RM) build to an area where you have write access, and use Options -->Set base path... to tell GoGui where the root of your installation is. (See See Implementing Scenarios 2 or 3.) Caution: When setting your GLAST_EXT environment variable, remember to type in the path; do not attempt to use the Browse.. button to set this, or any other path, starting with afs unless it's reachable from your home directory without having to go up to /. It can take a very long time – or even hang the application.

GoGui Menus

Customizing GoGui

The Qt widgets behave in predictable fashion; for example,you can:

• Adjust the window size, adjust size of panes within the main window.
• Hide or show individual toolbars (right-click in the general area of the icons).
• Detach the entire left Navigator part of the window.

Note: Of these adjustments, the only one currently preserved from session to session is size of the GoGui window.

GoGui Toolbar

For development purposes, you will also need access to a base release, i.e., a source distribution of a supported container package such as ScienceTools or GlastRelease.

Note: At the time of this writing (09-08-2010), the SCons version of GlastRelease was not yet available.

Checkout new container package:

Note: This operation essentially performs the same function as the installer, except that it does not handle the external libraries.

1. Click on the checkout-container icon in the tool bar (also available in the CVS menu).

2. Enter:
   1. ContainerName (e.g., ScienceTools or GlastRelease).

2. Tag (e.g., ScienceTools-09-17-00)

Note: Click on the tags.. button to see a list of candidates.

3. Parent path where you want the container package to go; for example:

/u/gl/userName/GoGui_test/packages/

Note: The parent directory must pre-exist, or the checkout will fail.

Container Checkout

3. Allow a couple of minutes for the checkout to complete.

Notes:

• At the time of this writing (09/24/2010), there is no feedback until it's over.

If successful, the container will now be your base installation, and the GoGui Post Checkout window will update accordingly.

Invoke SCons to Build or Clean a Package

1. Select package.

2. Then click on:
   • item on tool bar,
   • item in Build menu, or
   • right-click on package and click on desired operation in context menu.

By default you will get a debug/no-opt build. You can change these settings by clicking on build options.. in the Options menu.

Warning! SCons is much more thorough about cleaning (and building) than CMT. For example: If SCons is asked to do a clean on xmlBase, in addition to deleting all files built from the xmlBase build directory and all files from xmlBase installed in the top-level exe, bin, lib, data, xml or include directories, SCons will also remove all build products from packages it depends on. xmlBase depends only on facilities, so the additional files removed in this case are All object files (.os in this case, since facilities builds a shareable library). Facilities library (both local in the package and installed copy). Facilities includes in top level include directory used by xmlBase, namely commonUtilities.h and Util.h. Note: At the time of this writing, this is default SCons behavior; however, this behavior may change in future releases. If asked to build xmlBase, SCons will also build or install any products from facilities which it requires, and which are absent or not up to date.

Run a Program

Locate the program by either:

• Selecting the package, which builds the program, and then finding it in the package file hierarchy under build/redhat4-i686-32bit-Debug (or similar).

Note: The exact value of the last field, known as the variant, depends on the operating system (OS) and compiler options.

   OR

• Select top container package and find the name of the desired program under exe/<variant> or bin/<variant>.

Also see: Why is the program in three different places?

• SCons will operate on the one with the "highest" directory name alphabetically,
  e.g. xmlBase-04-04-02 in preference to xmlBase-04-03-01 or plain, unadorned xmlBase.

• SCons will always use a version from the supersede area in preference to the base area if one is available.

Tip: If that's not what you want, you can explicitly exclude a package and SCons will ignore it.

• Its display icon in the package list will acquire a red X (for a head package it will look like ),

and

• various functions for that package will be disabled.

Known issue: There is a bug somewhere that has not yet been tracked down, causing a delay in these visual changes; typically, they don't happen immediately.

Tip: To force them to happen, click on a package. If there is a supersede path, you should click on one package in the base path and one in the supersede path to ensure that the display is totally up to date.

Set up a Supersede Directory (as of 0.9.0)

From the Options menu, select: Set supersede path..  A dialog similar to the one for Set base path will be displayed.

Notes:

• Packages in the directory you select will be treated as part of your setup; however,
  it will no longer be possible to build packages in the base installation.
  • Once there is a supersede directory, SCons treats the base installation like an external library.
  • Behavior of SCons (and therefore GoGui) may not be what you expect.

See the Fine Points section for a discussion of various oddities.

Additional CVS Operations

• CVS update (Normal.)
• CVS -n update (Show what update would do, but don't do it.)
• CVS update -A (Update and remove sticky tags.)
• CVS commit changes.
• CVS rtag.

All of the above are available from package context menu, or from CVS menu in top menu bar once a package is selected. The commit icon also appears in the top toolbar.

• CVS diff a file is available from file context menu.

• Check out a package.

Miscellaneous Functions

• Terminal window. Bring up terminal window with setup done (setup is not done properly yet for Windows).

• Refresh package hierarchy display.

• Remove a package.

• Find. Type a string in the space just left of the icon, then hit Return or Enter on your keyboard or click the icon. GoGui will highlight the next occurrence of the string in whichever pane of the tabbed panel is visible.

• Browse a file. Select the package of interest in the upper left pane, then find the file in the package browser (lower left pane) and right-click. Select browse and the file will come up in its own window.

Note: You can select and copy text from this window, but you cannot modify the original file.

• Select preferred editor. Click on preferred editor.. in the Options menu.

Note: By default the editor will be set to write (executable name for WordPad) on Windows, and to emacs on Linux.

• Edit a file. Right-click on a file in the package browser and select edit. The file will come up in your preferred editor.

Fine points

• SCons init. The first time SCons is invoked, it has to verify that all the external libraries requested by the application (e.g. ScienceTools) are where they should be, and it has to work out all the dependencies among all files in the application. These are time-consuming operations.

For the external libraries, SCons will use cached information if it can. However, by default, each command-line invocation of SCons will re-check dependencies. While this ensures that SCons will always have correct information, it also slows down the application development cycle to an annoying degree, especially on Windows.

Most of the time dependencies don't change; that only happens if, for example, the developer changes the set of includes required by a source file. To avoid performing the dependency check with every SCons operation, GoGui starts up an SCons process with the --interactive flag the first time you ask for an SCons operation and keeps it around.

Note: If you did this from the command line you would get the prompt: scons>>>. You will see this prompt in GoGui's output pane. Subsequent requests are made to the same process.

• SCons init icon. If you believe you might have changed the dependency structure, you can always force GoGui to recalculate it by clicking the SCons init icon. This will call SCons to build a special target known as "NoTarget"; the only effect is to do the externals and dependency checking. If you start up GoGui and attempt to do a build or clean without first doing an explicit init, GoGui will do the init for you, then do the build or clean.

• SCons queue You may make several SCons requests (global init; per-package or global build, or clean) and they will be queued, to be executed in order requested. The status bar at the bottom usually contains text like

  SCons request count: 0

If your very first SCons request is a build or clean, GoGui knows to do an init first, so in that case the count will be 2 even though you only made one explicit request.

• Stop running icon (Stop SCons process. Discard any queued requests.)

Clicking the Stop running icon icon when SCons operations are in progress will cause the entire queue to be cleared and another init will be required before you can do anything else with SCons.

• Why is the program in three different places? – There are:

• Specify build target.
• Stop SCons process. Discard any queued requests.