What is FCM?

The FCM (Flexible Configuration Management) system is designed to simplify the task of managing and building source code.  The FCM system consists of 3 components:

• Integrated Configuration Management, wiki and issue tracking system
  
  • Provides facilities for making changes to source code in a controlled manner
  • Version control is provided by the open source tool Subversion. The source code and its history are stored in a central database called the repository.
  • The web-based tool Trac allows changes to be viewed and documented.  It provides an integrated issue tracker, wiki and repository browser.
• Extract system
  
  • Provides the interface between the Configuration Management and Build systems.  Codes is extracted from the repository and presented in a suitable form for the build system.
    
• Build system
  
  • Allows the source code to be compiled with a minimal amount of configuration.

The diagram below illustrates how these components fit together.

Figure 1: FCM System Components

For further detail about the FCM system see the System Overview, part of the FCM user guide.

What's new and improved?

The FCM system is a completely different way of working.  Here is a summary of the new and improved features that the system brings.

Subversion

• Full source file history accessible on the web via Trac.
• Source code is edited directly in your workspace.
• Source code is under version control and is stored in a directory tree as opposed to the old style flat UMPL.
• Atomic commits - either all your changes are committed to the repository or nothing is committed.

Branches

• Parallel development is possible via the use of branches.  There is support for merging multiple changes.  Any conflicts that arise during development must be resolved before the commit to the repository is accepted.
• Support for graphical differencing and merging.

Trac

• Integrated wiki and issue tracker (Trac)
  
  • Issue tracker supersedes modset headers
  • Browser for subversion repository, including project trees, revision logs and changesets.
  • Roadmap feature for managing project releases

Build

• Simple configuration
• Full Fortran 90/95 support
• Better control for setting compiler flags
• Supports parallel make
• Supports a separate pre-processing stage
• Inherits objects and setting from pre-compiled builds
  

Extract

• Extracts source code from the repository to your working directory.
• Combines source code from multiple branches, as long as there are no clashes
• Can combine source code from different repositories
• Mirrors code to the remote system for building, as required.
• Generates a configuration file for the build system.

Other

• Access to all functions is via the fcm command
  
  • Command syntax is simple and easy to use
  • A GUI wrapper is available for Configuration Management (CM) commands
  • CM commands are only on PUMA
• Comprehensive User Guide
  
  • See http://ncas-cms.nerc.ac.uk/..... or http://puma.nerc.ac.uk/FCM/.....  (Update Link)

• Used throughout the Met Office to management projects like VAR, OPS, NEMO etc. 

Importing the UM into FCM 

• Code is now stored in a directory tree, see figure 2 below.  Files which were in multiple sections under the old system now live in one of them only.
  
• #include <x/x.h> have been changed to #include "x.h"
• #include "updefs.h" lines have been removed
• Fixed format Fortran has been converted to Free format
• All comments begin with !
• New operators have been implemented (e.g. == replaces .EQ.)
• Each Fortran source file now only contains an individual compilable program unit
• Source file names match program unit names
• All subroutines end with
  END SUBROUTINE <name>
• Addition of  "!DEPENDS ON:" directives.  A 'depends on' line must be added immediately above subroutine calls.  This is used by the build system to determine what needs to be built.  If you don't include this line then the subroutine will not be built.

Figure 2: Repository Design

 

Comparison to Current Methods

Take a look at the UM repository via the Trac web interface - http://puma.nerc.ac.uk/trac/UM - You will need to login in with the userid/password sent you in the "Welcome to FCM" email.  Have a look at the...... <to complete...>

Branches and Working Copies

• Subversion configuration manages the repository of all the UM code.
• The trunk is the consolidated code that goes into each UM release.  The trunk in the NCAS UM repository will always mirror that of the Met Office.
• A release is a specified revision of the trunk (identified by a keyword).
• Branches are the method of making and tracking changes.  Branches are held in the repository.
• A working copy is a local copy of a branch, which may have changes to it.

In order to use FCM you need to have a basic understanding of version control.  If you're not already familiar with Subversion or CVS then it is recommended that you read the chapter Fundamental Concepts in the Subversion Book. To gain an understanding of how to perform most of the normal day-to-day tasks using code management, read the Chapter Basic Usage in the Subversion book for a guided tour.

Insert diagram of trunk and interaction with met office.  Show how branches are visualised and how revision numbers are incremental over the whole repository not to an individual user.  See slide 24 in MO presentation. 

Typically to make a code change and build a new model executable you would go through the following steps.

1. Create a new branch either using the FCM commands or via the FCM GUI interface.
2. Checkout the UM code. This results in a directory in your workspace containing a copy of the UM code.
3. Make changes to the code
4. Build the code and create a model executable
5. Commit code changes back to the branch

This process is depicted below.

Figure 4: Typical Workflow

Types of Branches

When you create a new branch you have the option of creating various types of branch, this is merely a way of grouping branches of a similar type of work together.  Most of the time you will want to create a development branch, this is the default.  If you just want to try something out, then create a test branch.

Development 

Intended for development work that will eventually be fed back to the Met Office and incorporated into a future release of the UM.  Development branches will have a pathname of the following form:

Test

Branches of type test are for temporary work, that is not intended for a future UM release.  Test branches will have a pathname of the following form:

Others

-Package branch: Used for combining multiple development branches.  A package branch would also be used for managing project development like UKCA, UJCC, etc...

- Configuration branch: Used for combining multiple packages and development branches.

FCM Keywords

The UM repository is located at svn://puma/UM_svn/UM.  Pathnames (or URLs as they are called in Subversion and FCM speak) to branches can be rather unwieldly.  FCM provides keywords which are a shortcut to specifying these URLs making them shorter and much easier to remember.  Keywords are specified with the fcm: prefix.

For example, the following commands are equivalent:

fcm ls svn://puma/UM_svn/UM/trunk

fcm ls fcm:fcm_tr

Standard keywords defined are:

Next Steps

Now that you have an overview of what FCM is and how it works, it's time to get started!  The UM FCM Tutorial <insert link here> is designed as a "hands-on" approach to familiarise yourself with the basic concepts and working practises.
 

P

Note: Information in this document is based on Met Office FCM presentation UM_train_dev.ppt