FCM 1.5 Release Notes
Author: FCM team

# FCM 1.5 Release Notes 22 January 2010

These are the release notes for FCM release 1.5. 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?

`fcm branch --list --show-all`
  New option to list all branches in a project.
`fcm keyword-print`: new command
  A command to print registered FCM keywords.
New method to manage revision keywords and other keywords related settings.
  See FCM User Guide > System Administration > FCM keywords for detail. Note: the `SET::TRAC` declaration is no longer supported.
`fcm update`: improvement
  The `fcm update` command applies to a whole working copy. If the working copy contains local changes, the command will prompt the user for confirmation.

## Minor Enhancements & Bug Fixes

`fcm build`: new `NO_DEP` declaration to switch off dependency checking
  A new declaration to switch off dependency checking for a given name-space. See the FCM User Guide > The Build System > Further dependency features for details.
`fcm build`: incorrect behaviour when dealing with the removal of TOOL declarations in incremental mode
  `fcm build` did not always handle the removal of TOOL declarations from the build configuration correctly in incremental mode. This has been fixed.
`fcm build`: new `TOOL::FC_MODSEARCH` declaration
  While most Fortran compilers search for the compiled module definition files (i.e. `*.mod` files) using the same option as the include search path (i.e. `-I`), some require a special option such as `-M`. The new `TOOL::FC_MODSEARCH` declaration allows such an option to be specified in the build configuration file.
`fcm build`: incorrect logic for handling `INHERIT::SRC` declarations
  The logic for handling this declaration was incorrect. This led to deleted files being incorrectly inherited. This has been fixed.
`fcm build`: incorrect logic for generating exclude dependency files for directory-based libraries
  These files were not being generated corectly. This has been fixed.
`fcm build`: incorrect logic for handling `SRC_TYPE`
  The system was unable to search for an include file whose type was declared via a `SRC_TYPE` declaration. This has been fixed.
`fcm build`: improvement to the Fortran interface file generator
  The logic to extract the calling interfaces of top level subroutines and functions from Fortran source files has been rewritten, based on the original logic developed by the European Centre for Medium-Range Weather Forecasts (ECMWF). In particular, the new logic will correctly handle 1) pre-processor directives with continuation lines, 2) continuation and comment markers in quotes, 3) BLOCKDATA program units in the source file, 4) TYPE components in variable identifiers, and 5) multiple program units in the source file. There are also improvements in the new logic to reduce the number of useless declarations and module imports in the generated interface block.
`fcm commit`: improvement to the commit message delimiter
  Some users found the old delimiter line confusing. This has been improved.
`fcm commit`: `svn:special` and `svn:executable`
  A symbolic link pointing to an executable target can cause a subsequent `svn checkout` to fail if the target is removed. To avoid the potential problem, `fcm commit` has been altered to remove the `svn:executable` property if a path is a symbolic link.
`fcm extract`: handling of file permission changes in incremental mode
  `fcm extract` did not handle file permission changes in incremental mode. This has been fixed.
`fcm extract`: handling of symbolic links
  Symbolic links cannot be handled safely by `fcm extract`. They are now removed from the extract.
`fcm extract` and `fcm build`: machine hostname
  The machine hostname will now be printed with the destination in the diagnostic output of these commands.
`fcm extract`: missing `RDEST` in the on-success configuration file
  Some `RDEST` declarations were missing from the on-success generated configuration file. This has been fixed.
`fcm extract`: improved options for the mirror sub-system
  It is now possible to specify the options of the `rsync` command in the extract configuration file. In addition, `ssh` is now the default remote shell command.
`fcm cmp-ext-cfg`: changed verbose option
  The `--verbose` option now requires an argument.

## Known Issues

Build inheritance limitation: handling of include files
  See the FCM User Guide > The Build System > Inherit from a previous build for detail.

## System Requirements

### Perl

The core part of FCM is a set of Perl scripts and modules. The following core/CPAN Perl modules are required to invoke the `fcm` command:

    Carp
    Cwd
    File::Basename
    File::Compare
    File::Copy
    File::Find
    File::Path
    File::Spec
    File::Spec::Functions
    File::Temp
    FindBin
    Getopt::Long
    HTTP::Date
    IO::File
    List::Util
    POSIX
    Pod::Usage
    Scalar::Util
    Sys::Hostname
    Text::ParseWords
    URI
    XML::DOM

The following Perl modules are also required if you want to use the `fcm gui` command:

    Tk
    Tk::ROText

At the Met Office we are currently using FCM with Perl 5.8.2 on AIX 5.3 and Perl 5.8.5 on RHEL 4.

### Subversion

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

At the Met Office we are currently using Subversion 1.4.3. Note: FCM 1.5 requires Subversion 1.4.x (but it has not been tested on Subversion 1.5.x or above).

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.2.1. 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 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 extract system uses rsync to mirror source file to another machine. At the Met Office we are currently using version 2.6.3

The build system 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 practise.
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.cfg.eg` file. If you wish to define keywords for your systems you will need to create the `etc/fcm.cfg` file. An example file, `fcm.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 the script `background_updates.pl` if it exists.
  This script is installed as standard in all our repositories.
examples/svn-hooks/background_updates.pl
  An example of how you may want to set up a `background_updates.pl` script to perform post-commit tasks for a specific repository. This script uses a lock file to prevent multiple commits in quick succession from causing problems.
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.
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.