FCM 2-1 Release Notes
Author: FCM team

# FCM 2-1 Release Notes 22 July 2011

These are the release notes for FCM 2-1. You can use this release of FCM freely under the terms of the FCM LICENSE, which you should receive with the distribution of this release.

FCM is maintained by the FCM team at the Met Office. Please feedback any bug reports or feature requests to us by e-mail.

## What's New?

No major new features in this release.

## Minor Changes and Bug Fixes

`fcm branch-create`

  if the `--ticket=N` option is not specified and NAME contains only a list of positive integers separated by `[_-]` (an underscore or a hyphen), the command will now assume that NAME also specifies the related ticket numbers.

  ticket numbers will now prefix the 1st line of the automatic commit log message.

`fcm cmp-ext-cfg`

  fixed `--wiki-format=TARGET` option, broken at 2-0.

`fcm export-items`

  fixed `--new` option, broken at 2-0.

  now generate real `v*` directories and revision directories as symbolic links.

  `fcm_update_version_dir.pl` removed.

`fcm make`

  build: allow space between `#` and `include` for `#include` syntax in C or Fortran source files requiring pre-processing.

  build: will now fail when an invalid target key is specified.

  build: correctly support compilers and linkers that require a space between an option flag and its argument.

  build: will no longer call `ar` for single file link.

  build: improve error message if a target does not exist in the expected location following an update.

  build: `target-rename` declarations are now non-cumulative, as documented.

  build: `build.prop{file-name-option.f90-mod} = case=upper` can now be specified for compilers that generate `MODULE.mod` files for Fortran modules (as opposed to the more common `module.mod` convention).

  extract: `path-incl`, `path-excl`, `path-root` declarations no longer require a name-space.

  extract: fixed error handling when multiple processing.

`fcm mkpatch`

  fixed CLI prompt to confirm removal of old output directory.

  ensure initial branch creation is ignored.

commit message text editor

  `fcm branch-create`, `fcm branch-delete` and `fcm commit` now support the [helpers] editor-cmd option defined in `$HOME/.subversion/config`.

  `nedit` is no longer the default external text editor. `vi` is the default external text editor for the command line interface. `gedit` is the default external text editor for `fcm gui`.

configuration file syntax

  the `inc=LOCATION` is no longer supported for configuration files in the new part of the system.

  incorrect variable assignment syntax will now trigger an exception.

  leading and trailing spaces in modifiers and name-space are now ignored without triggering Perl warnings.

installation dependency

  `fcm` no longer requires the `XML::DOM` Perl module. It now uses `XML::Parser` instead. The latter is normally installed by default on most Unix/Linux platforms.

## Known Issues

Build inheritance limitation: handling of include files
  See the User Guide > FCM Make > Build > Build Inheritance for detail.

## System Requirements

### Perl

The core part of FCM is a set of Perl scripts and modules. At the Met Office, FCM runs on:

Perl 5.8.2 on AIX 5.3

  `Text::ParseWords` (core Perl module) is upgraded to version 3.22.

  Met Office users do not use the code management commands and the extract system on this platform.

Perl 5.8.5 on RHEL 4

  HTTP::Date in libwww-perl is required by `fcm extract` and the extract system in `fcm make`. (libwww-perl 5.79 installed.)

  XML::Parser is required by the code management commands. (2.34 installed.)

  Tk is required by the `fcm gui` command. (Tk 804.027 installed.)

### Subversion

To use the code management commands (and relevant parts of the extract system) you need to have Subversion installed.

FCM requires Subversion 1.4.x or above. At the Met Office we are currently using Subversion 1.4.3.

Note: you can use the extract system to mirror code to a remote platform for building. Therefore it is only necessary to have Subversion installed on the platform where you do your code development. If you use other platforms purely for building and running then you do not need to have Subversion installed on these platforms.

### Trac

The use of Trac is entirely optional (although highly recommended if you are using Subversion).

At the Met Office we are currently using Trac 0.11.7. Note:

- The `--trac` and `--wiki` options to the `fcm diff --branch` command allow you to view branch differences using Trac. This requires Trac 0.10 or above.
- Some of the example scripts in the `examples/` directory require Trac 0.11.

### Other Requirements

The `fcm conflicts` command requires xxdiff. At the Met Office we are currently using version 3.1. The `fcm diff --graphical` command also uses xxdiff by default although other graphical diff tools can also be used.

The `fcm make` command uses `gzip`. At the Met Office we are currently using gzip 1.2.4 on AIX 5.3 and gzip 1.3.3 on RHEL 4.

The extract system uses `diff3`, (which is part of GNU diffutils), to merge together changes where the same file is modified by two different branches (compared with the base branch). At the Met Office we are currently using version 2.8.1.

The mirror system uses rsync to mirror source file to another machine. At the Met Office we are currently using version 2.6.3

The deprecated `fcm build` requires GNU make. At the Met Office we are currently using version 3.80.

FCM is intended to run on a Unix/Linux system. It is currently used at the Met Office on Linux (RHEL 4.8) and AIX 5.3.

## Installation

FCM is distributed in the form of a compressed tar file. Un-pack the tar file into an appropriate location on your system. Add the `bin/` directory into your PATH environment variable. Once you have done this you should now have full access to the FCM system, assuming that you have met the requirements described in the previous section.

You should find the following contents in the distribution:

README
  The README file contains the internal revision number of the release.
COPYRIGHT.txt
LICENSE.html
  The FCM license and other copyright information.
bin/
  Contains the `fcm` command and other utilities.
doc/
  System documentation.
doc/release_notes/
  Contains these release notes. It also contains the release notes for all previous versions which may be useful if you have skipped any versions.
doc/user_guide/
  Contains the FCM User Guide.
doc/standards/
  Contains the FCM Perl and Fortran coding standards. The Perl standard describes the standards followed by the FCM code. The Fortran standard contains some specific advice on the best way of writing Fortran code for use with FCM as well as more general advice on good practice.
doc/collaboration/
  Contains the External Distribution & Collaboration for FCM Projects document which discusses how projects configured under FCM can be distributed externally.
etc/
  Miscellaneous items, including the `fcm/keyword.cfg.eg` file. If you wish to define keywords for your site you will need to create the `etc/fcm/keyword.cfg` file. An example file, `fcm/keyword.cfg.eg`, is provided which is a copy of the file currently used at the Met Office. For further details please refer to the section FCM keywords in the System Admin chapter of the User Guide.
examples/
  Contains various example scripts which you may find useful. Note that these scripts are all specific to the Met Office and may contain hard coded paths and email addresses. They are provided in the hope that you may find them useful as examples for setting up similar scripts of your own. However, they should only be used after careful review to adapt them to your environment.
examples/etc/regular-update.eg
  An example of how you might set up a cron job to make use of the `<repos>.latest` file (see `examples/svn-hooks/post-commit-background`).
examples/lib/
  Contains the `FCM::Admin::*` Perl library, which implements the functionalities of the FCM admin utility commands.
examples/sbin/
  Contains a selection of useful admin utility commands.
examples/svn-hooks/pre-commit
  This script restricts write-access to the repository by checking the following:
  - It executes the Subversion utility `svnperms.py` if it, and the associated `svnperms.conf` file, exist. This utility checks whether the author of the current transaction has enough permission to write to particular paths in the repository.
  - It checks the disk space required by the current transaction. It fails the commit if it requires more than 5Mb of disk space.
examples/svn-hooks/post-commit
  A simple post-commit hook script which runs the script `post-commit-background` in the background.
examples/svn-hooks/post-commit-background
  This script runs in the background after each commit.
  - It updates a `<repos>.latest` file with the latest revision number.
  - It creates a dump of the new revision.
  - It calls `post-commit-background-custom` if it exists.
examples/svn-hooks/pre-revprop-change
  A simple pre-revprop-change hook script which runs the script `pre-revprop-change.pl`.
examples/svn-hooks/pre-revprop-change.pl
  If a user attempts to modify the log message of a changeset and he/she is not the original author of the changeset, this script will e-mail the original author. You can also set up a watch facility to monitor changes of log messages that affect particular paths in the repository. For further details please refer to the section Watching changes in log messages in the System Admin chapter of the User Guide.
examples/svn-hooks/post-revprop-change
  A simple post-revprop-change hook script which invokes the `trac-admin` command to `resync` the revision property cache stored in the corresponding Trac environment.
lib/
  Contains the Perl library of FCM.
man/
  Contains a basic manual page for `fcm`.
t/
  Contains unit test for FCM.
test/
  Contains regression tests for FCM.
test/test_include/
  Contains simple test code to check how your chosen compilers handle include files (see Known Issues).
tutorial/
  Contains the files necessary to set up a Subversion repository for the FCM tutorial. This will allow you to follow the tutorial section in the User Guide. See `tutorial/README` on how to set it up.