8 Shared and External Libraries

The CCSM has a special csm_share libary. This share code was build with ccsm in mind. It has modules that define constants, handle system calls, facsilitate component communication, and carry out internal timing among other things.

The CCSM also may use a number of general-purpose software libraries that are or are not widely distributed and in some cases relatively new. Examples include locally developed utility libraries like a timing library or calendar manager as well as externally developed libraries like the Model Coupling Toolkit (MCT) developed at Argonne National Laboratory or the Message Passing Handshaking (MPH) developed at Lawrence Berkeley National Laboratory. It is desirable that all such libraries are integrated into the CCSM in an orderly and consistent fashion. This section describes the policies for integrating such libraries.

8.1 csm_share

csm_share code will be a unique ccsm ``component''. The source will be available in the repository similar to all other components and it will be compiled directly into ccsm components as necessary. The requirements for csm_share are

• Must be multi-task and thread safe.
• Must meet general CCSM software engineering standards.
• Must compile and run with all components.
• Source code must be particularly well tested, validated, and documented because of its critical role.

Unit tests should be built for csm_share.

8.1.1 Share Constant Module

When more than one model component uses the same constant, that constant should be defined in the share constant module and all components that use that constant should use the value defined in that module. These can either be manually verified by checking that constants in components agree with the values in the module or by specifically ``using'' the shr_const_module and defining internal constants from the module directly. The second method is recommended. The share constants values will be reviewed periodically by scientific staff and new constants may be added from time to time.

The values of the share constants are

``to be filled in later''

8.2 External Libraries Integration Policies

For the convenience of users and also for faster modification and debugging in case of problems, we will bundle these library source codes with the CCSM distribution. These libraries will be integrated into the CCSM as follows:

• There will be subdirectories under the ccsm*/utils directory that will contain the different libraries.

• Each library will have its own Makefile or will use the standard CCSM Makefile.

• The library source code and Makefile will be committed into the CCSM repository. Library source code will be updated as necessary when new releases become available. If the codes are kept under revision control elsewhere we will commit versions in which CVS or other directories linked to the remote repositories have been removed.

• Each library will be built into a true lib*.a. The CCSM will link to these libraries. Files in the utils directory will NOT be compiled into CCSM components using an extension to the source path (like csm_share is doing now).

• The csm_share directory will continue to exist and will follow the source path convention for build. At some time in the future, csm_share might be placed under the utils directory and be required to meet the lib*.a standard.

In addition to the above we set certain requirements for external packages. These are:

• Usage of a utility/library must be well documented. In particular, #include or use statements that are required, subroutine/function interfaces, and examples should be provided.

• Unit testers should be provided with the utilities. In general the unit testers will be in a sub-directory beneath the given utility directory called "unit_testers".