12.7 Release Notes

What’s New in this Release?

Cougaar 12.7 contains no significant new functionality. It is primarily about consolidating down to a smaller subset of the code that represents the core functionality and re-organizing to make it easier to install and use, particularly for developers of both applications and the core software.

Contents

For documentation on the various zip, jar, and config files included in this release, please see Release Structure.

Git info

The release is on branch origin/B12_7 and tagged with R12_7.

Changes:

  • Many modules have been removed from the release. The current set of modules (listed here) only provide the core functionality currently being used. This makes Cougaar more supportable in the long term, plus it makes it easier for a new developer/user to focus on the parts of Cougaar that matter. (Obsolete modules still exist in the repositories, both in the older releases of their original repositories and in the new attic and examples repositories.)
  • Cougaar now requires far few third-party libraries, even though the libraries were not updated for Cougaar version 12.7. The list of third-party libraries has been updated to reflect those libraries necessary for 12.7. In the core repository, module jars are still the all the 3rd party jars, even the obsolete ones; however, the build process only copies the ones that are needed into the cougaar/sys directory where they get zipped up in the Cougaar build process.
  • The TrimCougaar module (and Eclipse project) has been replaced with the Cougaar module/project. The name change reflects the fact that this contains/references the entire supported Cougaar base code and not just some subset. There have also been a variety of changes to its structure to make it easier to (i) use as the starting point for application development, (ii) access the underlying Cougaar source code (when cloned from Git repositories), and (iii) rebuild from source.
  • The demos/tutorials that were retained have been updated to work with the new approach to defining, developing, building and deploying applications based on the new Cougaar module. A few variations on the Hello world tutorial have also been added.
  • There are changes in how to install and run Cougaar. The current approach is documented on the pages Installing and Running Cougaar. A goal of this release was to make the process of installing and running easier.
  • The zip files produced are different. The new zip files are described below.
  • Additional functions in the API have been modified to support generics.

Release notes for older Cougaar revisions can be found in the Release History.

Requirements

Cougaar requires Java version 1.6 (aka Java 6). For details, please see the Installation Guide.

Installation

Please see the Installation Guide. (The Overview Slides are now out-of-date.)

Documentation

For additional details, please review the following documentation:


Known Limitations and Features

  • The change to use Java generics may require modifying existing applications.
  • In certain versions of *nix, the permissions on the executable files (e.g., cougaar/bin/cougaar) may be lost in the process of zipping/unzipping, and the user may need to manually make them executable.
  • Cougaar will not build with Java 7 due to its JDBC 4.1 being incompatible with JDBC 4.0. Code changes necessary for JDBC 4.1 are present in the source, but commented-out.
  • The fact that javaiopatch is now out-of-date means that complex planning objects (tasks, allocations, etc.) cannot be persisted (and hence also cannot move with agents between nodes).
  • The javadoc is built without the special-purpose (but currently out-of-date) doclets and taglets to handle Cougaar-specific annotations
  • Please note that if you change SimpleAgent.xsl do not change the value of threadService from full to trivial unless you also change to metrics=trivial. The values must be in sync for consistent use of dependent libraries.


Support

For information on problems that were detected after this Cougaar version was released, please see the Online errata page.

Contents of this Cougaar Release

This section documents the contents of this release and the general layout of Cougaar software modules. When you download a Cougaar release, there are several logical pieces.

BUILD ORGANIZATION

As described on the page Installing, there are two different ways to download the Cougaar software: from zip files or from the repositories. The big differences between the two methods are that:

  • only the repositories contain the base Cougaar source code (both the zip files and the repositories contain the tutorials source code)
  • only the zip files contain prebuilt javadoc and prebuilt jar files

There are eight different repositories, seven (all required) containing the current Cougaar base and one (optional but recommended) containing all the tutorials. Each of the repositories contain a set of modules as listed here. After cloning all of the repositories onto a local machine and importing all the projects into an IDE such as Eclipse, the tutorials should be all ready to run.

The zip files available for download are:

cougaar.zip Cougaar runtime – all “lib/” (runtime jars), “clib/” (build-time jars) and “sys/” (3rd party jars) jar files, run scripts (“bin/”, configuration files (“configs/”, including the usual configs/common directory), and minimum documentation (“doc/”). Additionally, most modules (see below) include directories with additional documentation and configuration files. Javadoc and source code is not included. (The source code is now only available by cloning from repositories.)
tutorials.zip All the tutorials described here are included in this zip. These include the source and build files to allow their use as a template for building new applications. They can be loaded into eclipse or run from the command line.
cougaar-api.zip The Javadoc for all the main cougaar classes in one place. Unpacks to “/doc/api”, putting the Javadoc with the module where the source originates.
md5sums.txt MD5 checksums for all the above zips.
sha512sums.txt SHA512 checksums for all the above zips.
CougaarOrgProjectSet.psf A file that can be used with Eclipse to automatically clone all the required repositories and import the required projects from the repositories.

After downloading and unzipping the files cougaar.zip and tutorials.zip, the tutorials should be all set to run either in Eclipse or from a command line interface as described on the page about Running Cougaar.

MODULE LIST

The Cougaar software distribution (cougaar.zip) contains a number of separate modules of related classes with supporting documentation and sources. The modules tend to each be associated with their own Eclipse project. The list of these in the current build are provided at Modules in GIT Repositories.

INTRA-MODULE ORGANIZATION

Each module subdirectory is organized in a similar way in the source repository (note that each module has only a subset of these components/subfolders):

build.xml ANT compilation script (build-generated for CougaarSE modules).
src/ Head of java sources for module, arranged like javac would expect to see in a CLASSPATH.
bin/ Executables, scripts and support
data/ Arbitrary (static) data for runtime use.
doc/ Documentation, in text and html
configs/ Configuration directories. Usually contains only subdirectories, each is a valid configuration.
examples/ Like src, but is never shipped compiled. The build process should attempt to compile and regression-test anything in here, but generated class files are never actually shipped.
regress/ Unit test sources for this module. Will be compiled and run by build process, reporting on compile, runtime and test failures. produced binaries are never installed or packaged. test should be the root of a java package tree – consider following “junit” format conventions.
eclipse/ Contains the launchers used to execute the application inside of Eclipse. (Note that there are also .project and .classpath files to define the associated Eclipse project.)

PACKAGE ORGANIZATION

Software intended to replace core functionality should match the below package layout (or provide detailed arguments why it should be changed).

Software intended to augment the core and/or provide optional core functionality, but is not intended to replace the “standard” software suite, should mirror the above layout rooted in a new “organization/project/product-specific” package rather than override the core’s “org.cougaar” package names. For example, an alternate implementation of the agent base class

    core/org.cougaar.core.agent.AgentImpl

which was optimized for small devices might be delivered as part of company “foo”‘s module as

    fooco/com.foo.cougaar.palmtop.agent.EmbeddedAgent

where:

    "fooco/" is the module
    "com.foo." is the company package prefix
    "cougaar.palmtop." is the project's root
    "agent" is the parallel to the core's package.
    "EmbeddedAgent" is the class name

None-core functionality should follow standard java package arrangement standards and so should not intersect with any core packages. In particular, “org.cougaar” may only be used by core cougaar software.