FCM 2-2 Release Notes
Author: FCM team

# FCM 2-2 Release Notes 15 June 2012

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

## Contents

## Highlight Changes

`Subversion 1.6`

  Code management commands and extract system tested with Subversion 1.6. Note that Subversion 1.4 is no longer supported and Subversion 1.5 has not been tested.

  We experienced some non-repeatable problems using Subversion 1.6 where we got incorrect results from a merge. Running `svn cleanup` appears to avoid the problem. Therefore this is now run prior to any update, switch or merge command.

`fcm branch-create`

  `-rREV` option no longer supported - add a peg revision to the source if necessary.

`fcm branch-list`

  significant improvement to speed.

  multiple projects can be specified as arguments.

  more options for advanced listing.

  `-rREV` option no longer supported - can use peg revision for each project in the argument list.

  no longer returns 1 if 0 branch is found - non-zero value reserved for fatal errors.

  new `--quiet` option to print names of matched branches only.

  `-v` option no longer supported - use new `--url` option to print branch names as full URLs instead of FCM location keywords.

  minor change to output format.

`fcm conflicts`

  handle resolution of common cases of tree conflicts.

`fcm make`

  build: change in how the dependency tree is created. This fixes the behaviour where the system incorrectly reports cyclic dependency. An example situation is where a recursive `subroutine a` calls `subroutine b` which calls `subroutine a`. The object file target `a.o` has a dependency on `b.interface` and the object file target `b.o` has a dependency on `a.interface`. Previously, `b.interface` would also depend on `b.o` which would result in a cyclic dependency. This fix changes the internal data structure for representing a build target. Use of `fcm make` at release 2-2 to build incrementally or to inherit a build created by `fcm make` at release 2-1 or before will result in an incorrect behaviour or failure. Use the `--new` option to start a new build if the build destination is known to contain an existing build created by `fcm make` at release 2-1 or before.

Flexible repository layout

  FCM code management commands no longer insist on a rigid layout of its Subversion repositories. Behaviours can now be configured per repository. In its default setting, FCM code management commands no longer insist on `branches/` and `tags/` being present in a project.

## Minor Changes and Bug Fixes

`fcm branch-create`

  new `--switch` option to switch the current working copy to point to the newly created branch.

`fcm branch-delete`

  new `--switch` option to switch the current working copy to point to the trunk after the branch deletion.

`fcm branch-diff`

  fixed: the command will no longer fail when called with an unmodified sub-tree of a branch.

`fcm build/extract`

  fixed multi-level inheritance destination search path.

`fcm commit`

  fixed incorrect behaviour on `svn commit` failure.

`fcm make`

  build: fixed multi-level inheritance destination search path.

  build: do not use relative path for inherited include paths and object file paths in command lines.

  build: fixed duplicated dependent targets being reported as missing dependencies.

  build: fixed incorrect behaviour with Fortran `*.mod` target in incremental mode where only a build property (e.g. a compiler flag) associated with the source file of the `*.mod` target is modified.

  extract: fixed handling of add/delete of files in file system locations during incremental extract.

  extract: fixed Perl warning when a file system location contains a symbolic link with a non-existent target.

  extract: fixed Perl warning when 2 diff locations both add a file of the same name but with different contents.

  extract: improved merge conflict diagnostics.

  extract: allow unmodified location in the configuration to pass in an inherited mode.

  mirror: fixed: create configuration file in target even if there is no source to mirror.

  mirror: always expand a relative path in a mirror target to a full path to allow it to be inherited. Some infrequently used modifiers in the `mirror.prop` declarations are added/removed for this fix.

`fcm merge`

  simplified prompts and diagnostic outputs.

  new `--auto-log` option for automatic merge. If the option is specified, the command will include the logs of the merged revisions in the commit log message automatically.

`fcm mkpatch`

  no longer uses patch files if they include a carrriage return in the middle of a line.

`fcm project-create`

  new command to create a new project and its trunk directory in a repository.

code management command line

  fixed logic for parsing URL@REV where URL is not a location keyword but REV is a revision keyword.

revision keyword

  fixed: fcm:revision property setting: trailing spaces in each line will now be ignored.

user guide

  tutorial: added section on tree conflict resolution.

  tutorial: removed references to `fcm gui`.

  added new annex: quick reference: tree conflict resolution.

Perl 5.12

  fixed: incompatibility problem.

## Known Issues

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

## System Requirements

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

Perl

  used by: `fcm`.

  versions at Met Office: AIX-5.3: 5.8.2 (see remark), RHEL-6.1: 5.10.1.

  remark: 5.8.2 on AIX-5.3: code management commands, the extract system of `fcm make` and the deprecated `fcm extract` are not used by Met Office users on this platform.

  remark: 5.8.2 on AIX-5.3: `Text::ParseWords` (core Perl module) is upgraded to version 3.22.

Perl module HTTP::Date

  used by: the extract system in `fcm make` and the deprecated `fcm extract`.

  versions at Met Office: RHEL-6.1: 5.833.

Perl module XML::Parser

  used by: the code management commands.

  versions at Met Office: RHEL-6.1: 2.36.

Perl module Tk

  used by: `fcm gui`.

  versions at Met Office: RHEL-6.1: 804.028.

Subversion

  used by: the code management commands, the extract system of `fcm make`, the deprecated `fcm extract`.

  versions at Met Office: RHEL-6.1: 1.6.17.

  remark: 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

  used by: (optional, but highly recommended as a companion to Subversion)

  versions at Met Office: 0.11.7.

xxdiff

  used by: `fcm branch-diff --graphical`, `fcm conflicts`, `fcm diff --graphical`.

  versions at Met Office: RHEL-6.1: 3.2.

  remark: The `fcm branch-diff --graphical` and `fcm diff --graphical` commands use xxdiff by default but can also use other graphical diff tools.

gzip

  used by: `fcm make`.

  versions at Met Office: AIX-5.3: 1.2.4, RHEL-6.1: 1.3.12.

GNU diffutils: diff3

  used by: the extract system of `fcm make`, the deprecated `fcm extract`.

  versions at Met Office: RHEL-6.1: 2.8.1.

  remark:: used to merge changes to source files modified by 2+ diff source trees (compared with the base).

rsync

  used by: the mirror system of `fcm make`, the deprecated `fcm extract`.

  versions at Met Office: AIX-5.3: 2.6.2, RHEL-6.1: 3.0.6.

  remark: used to mirror source file to another USER@HOST.

GNU make

  used by: the deprecated `fcm build`.

  versions at Met Office: AIX-5.3: 3.80, RHEL-6.1: 3.81.

## 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 10MB of disk space (or whatever is specified in the `pre-commit-size-threshold.conf` file.
examples/svn-hooks/post-commit
  This script runs `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
  This script only allows the modification of svn:log.
examples/svn-hooks/post-revprop-change
  This script runs `post-revprop-change-background` in the background.
examples/svn-hooks/post-revprop-change-background
  This script invokes the `trac-admin` command to `resync` the revision property cache stored in the corresponding Trac environment. If a user modifies 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. If the file `post-revprop-change-background-cc.list` exits, the script will also e-mail those in the list.
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.