- Algorithms- Infrastructure - Doxygen (public)- Doxygen (private)- Tutorials - Repository- Nightly Build- Nightly Regression- Feature/Bug Tracking- Build Targets- Procedure- Conventions- Tools

Download

CLARAty has two repositories: a public repository, and a private one. Each repository consists of a number of modules, where each module provides a capability. Some modules depend on others and CLARAty has an automated way of tracking these dependencies for configuration control, building, and running the software. We use a custom built tool called YaM Lite to track module dependencies. Almost always, you will only need to download and run certain modules in CLARAty. YaM Lite will figure out other modules that are necessary for downloading any given module.

All modules in the public repository have the same access privileges for all users with no restrictions. The software usage is governed by the CLARAty TSPA License.

The private repository has different access privileges for each module depending on Intellectual Property and ITAR restrictions. Access control is managed using AFS. Hence a JPL AFS account is required to access the private repository. Access is available for participants in NASA's technology program or other govenment funded programs.

The public repository currently contains a modest portion of the modules available in the private repository, but we continue to migrate modules from the private to the public repository.

Public Repository

Before you can download CLARAty modules, you need to install the YaMLite software locally. This light weight software provides the commands to checkout the necessary modules for your project.  You only need to install this once and you will be able to checkout modules for different projects. Begin by clicking below and downloading the file to your hard drive in a directory of your choosing.

Download

Yam Lite ver 1.23 (96.6 KB)

(for Linux, Solaris, Cygwin and OS X)

The first public release of CLARAty version 0.10-beta has been adapted from our private repository. In order to keep the public release light weight and manageable, we made some significant changes and upgrades to a few modules. Our goal was to eliminate deprecated functionality to make CLARAty easier to understand and use. We continue to use the private repository as the baseline for our rover systems until the point where functionality in the public repository reaches the critical mass that is necessary to support on-going research and development efforts. Because of the recent changes in some modules, this public release has had limited testing compared to the private repository which has been tested for many years. However, the public repository has been compiled for our three actively supported targets (Linux with GNU C++, VxWorks 5.5 for x86 and VxWorks for PowerPC). All regression tests in this release has succsessfully been tested on Linux platforms and partially tested on other platforms. Our goal is to continue to release modules that have been cleared for our public repository. We also plan to make several bug fixes updates throughout the year. At the appropriate time, we plan to migrate to use the public repository as a baseline for our rovers. We would also appreciate your feedback on the design, implementation and bugs that you encounter in this release.

Prerequisites

These instructions assume that the user is using the tcsh. If you are using bash as your shell type:

on the command line first.

If you are behind a firewall or have a local firewall enabled, be sure to open port 2401:tcp for the cvs pserver.

Install

Download the above file to your hard drive to a directory of your choosing. Decompress and extract from the tar file on the command line as follows:

Configure YaM Lite for your system by editing the sourceme file at: |<yam_dir>/config/site/public/sourceme.csh|, where <yam_dir> is the directory whre you extracted the .tar file plus /yam_lite_1.23.... The Readme file in that directory provides a definition for the environment variables. To start, the only necessary change is to point to the installed location of yam_lite.

If you have AFS installed on your machine, you can add the following environment variable to speed up the checkout process. If you do not have AFS, set the this variable to false.

Before you can download CLARAty modules, source the following file:

Checkout desired CLARAty modules, build, and run.

Private Repository

This repository is accessible to developers and affliates who are providing component technologies through one of the NASA programs (e.g. Mars Technology Program). To access this repository, you need a JPL AFS account.

Once you have your account and are a member of the group.claraty, you can start by logging into the JPL AFS cell as follows (you only need to do this once per machine, until your tokens expire (24 hours)).

Make sure that your JPL AFS account is setup properly (needed for both JPLers and external developers). Then, login into AFS as follows or using the appropriate procedure for your operating system:

Enter your password. You only need to do this once per machine, until your tokens expire (24 hours). Then, type:

or (sourceme_external.csh) if you are not on the robotics network at JPL.

At JPL, to cross-compile for a rover and to set up your paths to include VxWorks tools, run the appropriate rover/target script:
rocky8
rocky7 or
fido


More details

Checkout and Run

List Available Modules

To list all available modules in CLARAty, type:

In addition to listing all modules, you can use this command to list module dependency of a given module as follows:

or list the modules that use any given module as follows:

For a complete list of available yam commands and options, type:

Check out Modules For a New Sandbox

For A New Sandbox

To create a sandbox and check out one or more modules, type:

where <module> is the name of the module you want to check out. The module dependencies will automatically be added to the list. You will have a chance to inspect the module dependency list prior to proceeding. After computing the dependencies, the program will prompt you to continue. Use -noprompt to eliminate the question. If you also want to edit the list in the YAM.config that will automatically be generated, then add -edit option to the above command line.

For instance, to check out matrices, type the following: yam -d mysandbox -edit matrices

For an Existing Sandbox

To add modules (and their dependencies) to an existing sandbox, type:

To checkout modules from a YAM.config, use the following: yam checkout -c YAM.config. Please note that the YAM.config has some changes from older versions. In addition to having a YAM.config, you can also add individual modules on the command line.

You can also edit the YAM.config manually. You can add and remove modules, change the branch and tag for each module. If you remove a module in the YAM.config or change the tag/branch, then you will need to move the corresponding module in your sandbox out of the way as yam does not know what you want to do with it.  The checkout process skips existing modules.  Once you have completed your edits to your YAM.config, you can checkout the changes from your current sandbox as follows:

Build

You can either build an entire sandbox, or build individual modules in a sandbox. Additionally, you can either build for one target or for all actively supported targets.

Make Options

The make system provides a number of command line options for adjusting global build settings such as building with debug flags or controlling the verbosity of the make output. By default, the output of the build system is written in terse mode and the build does not include debug symbols for its object files. To build the software in verbose mode, use the option VERBOSE=1 or VERBOSE=all. To add debug symbols in the build, add CFLAGS=-g to the make command line. For example:

To make this change permanent for all future builds for that sandbox, edit the command line parser for make at <sandbox>/src/make/makefile/command_line_vars.mk. If you only want to make this change for one target, then edit the appropriate target file under: <sandbox>/src/make/target/<target>.mk. For example, if you always want to use verbose mode and have debug symbols for Linux targets with the GNU C++ compiler, then add the following line to <sandbox>/src/make/target/i86_linux_gcc.mk:

If you want to make all future builds use verbose mode, change the following line in <sandbox>/src/make/makefile/command_line_vars.mk from:

to

or to export VERBOSE=all.

You can also set link flags at the make command line using LFLAGS. For this and additional command line options, use: make help at the command line.

Entire Sandbox

To build an entire sandbox for the native host as defined by the script archname, type:

To get an explanation on each type:

The following rule is a combination of the above and more:

all: builds idl-links, srcs, links, deps, libs, bins, tests, moddeps, and libs.mk

If you issue the make libs command, it will automatically create the necessary links and dependency files before building the libraries. The same is true for building the binaries. We recommend that you build only the libs for large sandboxes at the top level (from cd <sandbox>). This will take considerably less time than if you were to issue a make all or make bins.  You can then build the binaries only for the module you are interested in.

Individual Modules

To build an individual module, change directory to the module of interest and follow the same procedure as above:

where rule is the same as the ones described for the top level directory.

Multiple Targets

To build for all supported targets, you can prepend alltgt to any build rule. For example:

To cross-compile for a non-native target, you can specify a YAM_TARGET . For example:

You can also set the YAM_TARGET environment variable

Run

After you have successfully compiled the binaries for a given module, you can run these binaries either on the host machine or on the target (if you cross compiled). If you are running a binary on the host machine, you can do either of the following:

where <architecture> for a host target is defined by the script archname and <application> is the binary you want to run. For example, on Linux targets type:

the run script sets your environment variables and LD_LIBRARY_PATH for the current sandbox.

The binaries are actually stored in their respective modules. You can run them directly from their respective modules as follows:

To run on a target, you must have cross compiled the binaries and libraries for that target. Here is how you can run on a VxWorks target or a QNX target.

Update and Diff a Sandbox

Entire Sandbox

To find out which modules have changed in the repository from the ones you have in your sandbox type:

To see the difference between your sandbox and the main trunk of the repository, use:

To update all modules in your current sandbox, type:

These commands will go through each module in your sandbox and execute the appropriate CVS command.

Individual Modules

From individual modules, use regular cvs commands to check the differences between the main trunk of the respository and your sandbox. You can also check what needs updating or do an update. So from the individual module, to see what needs updating without actually doing an update:

To find out the differences, type:

To update, type:

Commit Changes

Policy

• Before checking in or branching off the "main" codeline in CLARAty, please review the project policies.  If you have questions, please send email to: claraty-help@robotics.jpl.nasa.gov

Procedure

• Ensure that all the modules in your sandbox are up to date with the main codeline.
• Build all the modules you have changed for at least one of the actively supported targets. To build for all actively supported targets do the following:
  cd <sandbox>
  make alltgt-all
• Test the modules you have built sufficiently on these targets to convince yourself that the changes you have made are operational and do not break existing functionality
• Commit your changes using cvs:
  cd src/<module>
  cvs commit
• Update log, save, and continue
• Ensure that you have not missed to add new files before commit, type:
  cvs -n update

Process for merging a branch back onto the main branch

The following process describes how to merge a sandbox back onto main:

1. Check out the modules from main for which modification were made in the branch.
2. Compile and test the major features from main.
3. Check out the modules from the branch.
4. Move the code from the branch to the main sandbox that was checked out, a little at a time.
5. Rebuild, retest, fix any the broken code.
6. Check the main sandbox back in using the procedure above.

Create / Update Module Dependencies

To manually update the module dependencies for any given module, follow the steps below:

• Checkout the modules whose dependencies you want to update
• Build the module's dependency files
  cd <sandbox_path>
  make srcs
  cd src/<mymodulde>
  make moddeps
  
• Commit the updated module.dep files:
  cvs commit -m "comment" module.deps
  

A module's module.deps file tells what other modules this module depends on. Note that some modules have different dependencies under different operating systems such as Linux and VxWorks. The module.dep file is the union of dependencies for all supported targets defined by the environment variable ALL_TARGETS. The module.dep files are also automatically branched with the corresponding module to support different dependencies for branches.

If you modify code such that a module no longer depends on the same modules it used to, you'll need to rebuild moddeps for that module for any modules that depend on that module.

The CLARAty nightly build system automatically updates the module dependencies for those listed modules.

Create a New Module

• Send email to claraty-help@robotics.jpl.nasa.gov. Propose a module name that is:
  • Descriptive of the content of the module.
  • Does not currently exist. Check what is currently available using the module database.
  • Consistent with the CLARAty naming conventions.
• Administrators, follow this procedure:
  • Setup your environment
  • Create the new module. You do not need to be in the sandbox directory.
    yam mkmodule <module>
  • YaM will launch an editor to edit the Readme file for the new module. Enter an appropriate description. Put the date and name of the point of contact for this module.
  • YaM will send an email to the development team after successful completion of this process.
  • Once a module is created, YaM does not automatically add the module to your sandbox. Here is how you can add a module to your sandbox.

Branch

Policy

This section is only for CLARAty developers. You need to use this section if you are working on:

• A formal delivery of CLARAty modules for validation or other tasks
• A Level I or Level II milestone demonstration
• A major design change that will impact many modules

For more details see project policies.  If you have questions, please send email to: claraty-help@robotics.jpl.nasa.gov

Procedure

Tag Modules

To move from working on main to working on a branch, first you need to tag your primary module and all its dependencies. We recommend you checkout a sandbox only for that module and its dependencies. To tag a release:

Tag names should have the following format:

• delivery_<yr>_<month>_<name> - for example: delivery_2004_03_visual_tracking
• milestone_<yr>_<month>_<name> - for example: milestone_2004_09_instrument_placement
• feature_<yr>_<month>_<name> - for example: feature_2005_02_remove_impls

To remove a tag from all modules

Check out a Tagged Version

To check out a tagged module and its dependencies:

You cannot commit changes from a sandbox checked out above. To make modifications and commit changes, you will need to create a branch off the tag as follows:

Check out a Branch

Identify the tagged version from which you wish to branch. You cannot branch off the main trunk without creating a tag. To create the branch, type:

This command will create a branch if one does not exist or check out the module from the existing branch.  To make changes to a tagged version of a module, you need to branch the module and its dependencies.

Merge

To merge changes from sandbox that is on a branch back into main:

• Tag the head of your sandbox that is on the branch (see above)
• Check out a new sandbox on main
• Merge the changes from the start of the branch (tag: e.g. FY05) until the head of the branch (FY05-fix) as follows:
  
  cvs update -j FY05 -j FY05-fix
• Fix any conflicts that result from the merge. These are flagged by the merge command.
• Test the merged code
• Commit the changes on main as follows:
  
  cvs commit

Last modified: October 31 2007 14:42:12