New URL for NEMO forge!   http://forge.nemo-ocean.eu

Since March 2022 along with NEMO 4.2 release, the code development moved to a self-hosted GitLab.
This present forge is now archived and remained online for history.
1-3.html in vendors/fcm/current/doc/release_notes – NEMO

source: vendors/fcm/current/doc/release_notes/1-3.html @ 1980

Last change on this file since 1980 was 1980, checked in by flavoni, 14 years ago

importing fcm vendor
File size: 21.8 KB
Line 
1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
4<html xmlns="http://www.w3.org/1999/xhtml">
5<head>
6  <meta name="generator" content=
7  "HTML Tidy for Linux/x86 (vers 1st December 2004), see www.w3.org" />
8
9  <title>FCM 1.3 Release Notes</title>
10  <meta name="author" content="FCM development team" />
11  <meta name="descriptions" content="FCM Release Notes" />
12  <meta name="keywords" content="FCM, release" />
13  <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
14  <link rel="stylesheet" type="text/css" href="style.css" />
15</head>
16
17<body>
18  <h1>FCM 1.3 Release Notes<br />
19  30 January 2008</h1>
20
21  <p>These are the release notes for FCM release 1.3. You can use this release
22  of FCM freely under the terms of the <a href="../../LICENSE.html">FCM
23  LICENSE</a>, which you should receive with this distribution.</p>
24
25  <p>Note that FCM now requires Subversion 1.4.0 or later (previous releases
26  only required Subversion 1.2.0).</p>
27
28  <p>FCM is maintained by the FCM team at the Met Office. Please feedback any
29  bug reports or feature requests to us by <a href=
30  "mailto:fcm-team@metoffice.gov.uk">e-mail</a>.</p>
31
32  <h2>Contents</h2>
33
34  <ul>
35    <li><a href="#new">What's New?</a></li>
36
37    <li><a href="#fix">Minor enhancements &amp; Bug Fixes</a></li>
38
39    <li><a href="#req">System Requirements</a></li>
40
41    <li><a href="#ins">Installation</a></li>
42  </ul>
43
44  <h2 id="new">What's New?</h2>
45
46  <p>Build and extract:</p>
47
48  <ul>
49    <li>The syntax for declaring the extract/build destinations are unified.
50    The <code>DEST</code> (or <code>DEST::ROOTDIR</code>) declaration should be
51    used to declare the root of the extract/build destination. The
52    <code>DIR::ROOT</code> declaration is deprecated.</li>
53
54    <li>Users can no longer declare sub-directories in a destination.
55    Declarations such as <code>DEST::CFGDIR</code>, <code>DEST::SRCDIR</code>,
56    etc are no longer supported.</li>
57
58    <li>In configuration files, words or fields in a <em>label</em> can now be
59    delimited by a slash (<code>/</code>) as well as a double colon
60    (<code>::</code>). To improve readability, the convention is to only use
61    slash as the delimiter when referring to package names.</li>
62
63    <li>In a <code>true</code> or <code>false</code> declaration in a
64    configuration file, the system will now accept the following values as
65    false: <samp>0</samp>, <samp>&lt;empty string&gt;</samp>,
66    <samp>false</samp>, <samp>no</samp> and <samp>off</samp>. (It used to
67    accept <samp>&lt;any non empty string&gt;</samp> for <code>true</code> and
68    <samp>0</samp>, or <samp>&lt;empty string&gt;</samp> for
69    <code>false</code>.)</li>
70
71    <li>The build and extract caches are now located separately in
72    <samp>.cache/.bld/</samp> and <samp>.cache/.ext/</samp> respectively. In
73    most cases they will be upgraded automatically when you perform the next
74    incremental build/extract. However, if you use inherited build/extract, you
75    must upgrade the inherited build/extract before they can be used. To
76    upgrade an inherited extract, issue the following commands:
77      <pre>
78cd /path/to/inherited/extract/
79cd .cache/
80mkdir .ext/
81cp -r -p .config * .ext/
82</pre>
83
84      <p>To upgrade an inherited build, issue the following commands:</p>
85      <pre>
86cd /path/to/inherited/build/
87fcm bld
88</pre>
89    </li>
90
91    <li>Extra/common stages in the build/extract processes: <em>parse
92    configuration</em> and <em>set up destination</em>.</li>
93
94    <li>The build/extract destination (and the remote destination for extract)
95    will now be printed in verbose mode 1 or above.</li>
96
97    <li>A new command line option <code>--clean</code> for removing files
98    generated by previous extracts/builds.</li>
99
100    <li>An as-parsed configuration file will be generated for each run (if the
101    file differs from the previous run).</li>
102  </ul>
103
104  <p>Build:</p>
105
106  <ul>
107    <li>It is now more efficient to make <code>SRC</code> declarations for
108    files instead of the container directories. Container directories can still
109    be declared, but they will be expanded by the configuration file parser
110    into a list of source files within it. In addition, <code>SRC</code>
111    declarations no longer require the specification of package names - if it
112    is a relative path of the src/ sub-directory. If a relative path is
113    specified, it will be assumed a relative path of the src/
114    sub-directory.</li>
115
116    <li>For declarations such as <code>EXCL_DEP, PP, TOOL</code>, if a package
117    name is associated with the declaration, the system will fail if the
118    package is not declared or defined.</li>
119
120    <li>The system will now detect changes in <code>EXCL_DEP, INFILE_EXT and
121    OUTFILE_EXT</code> declarations in an incremental build.</li>
122
123    <li>It is now possible to make PP declarations down to the file level.
124    (Previously, it could only be done down to the level of the container
125    directories.)</li>
126
127    <li>The package name for a file used to be its root name (i.e. its basename
128    without the extension). It is now its basename, (although the system will
129    continue to support declarations down to the file's root name).</li>
130
131    <li>The declarations <code>TYPE</code> and <code>DEP</code> can now be used
132    to define the type and dependencies of a source file. (This replaces most
133    functionalities of the package configuration file.)</li>
134
135    <li>The build package configuration file is no longer supported.</li>
136
137    <li>The system now generates a single <samp>Makefile</samp> in the root
138    location of the destination. Hard coded directories should appear only once
139    at the top of the Makefile, provided that source files are only located in
140    the <samp>src/</samp> sub-directory of the build destination. (A build used
141    to have a top level <samp>Makefile</samp>, which included a
142    <samp>*.mk</samp> file for each source directory in the <samp>bld/</samp>
143    sub-directory of the destination.)</li>
144
145    <li>The <samp>fcm_env.ksh</samp> file is renamed <samp>fcm_env.sh</samp>,
146    which should work with the Bourne shell. (<samp>fcm_env.ksh</samp> is still
147    available via a symbolic link but is deprecated.)</li>
148
149    <li>The <code>--archive</code> or <code>-a</code> option will now archive
150    your build directories using the command <code>tar -czf FILE DIR</code>.
151    Consequently, the system will dearchive them using <code>tar -xzf
152    FILE</code>. If you have been using this option in your previous builds,
153    you should extract the archives manually using <code>tar -xf FILE</code>
154    before running <code>fcm build</code> in incremental mode. Remove the old
155    TAR files on success.</li>
156
157    <li>The linker command now defaults to the compiler of the language of the
158    program source file. (The default used to be <code>ld</code>.)</li>
159  </ul>
160
161  <p>Code management commands:</p>
162
163  <ul>
164    <li>Allow other graphical merge tools to be used in place of
165    <em>xxdiff</em> by modifying <code>bin/fcm_graphic_merge</code>.</li>
166
167    <li><code>fcm commit</code> will issue extra warning when a user attempts
168    to commit to or remove a branch belonging to another user.</li>
169
170    <li>The system has been modified to account for the improved support for
171    peg revisions using the <code>svn log</code> command in Subversion 1.4.
172    Unfortunately this means that Subversion 1.4.x clients are now
173    required.</li>
174
175    <li><code>fcm diff</code> now supports the <code>--summarize</code> option
176    which was introduced in Subversion 1.4.</li>
177
178    <li>Added alternate branching strategy in the <a href=
179    "../collaboration/">External Distribution &amp; Collaboration for FCM
180    Projects</a> document.</li>
181
182    <li>A number of limitations with the <code>fcm mkpatch</code> command have
183    been fixed. It will also use unified diffs where possible in order to
184    reduce the size of the patch and to make it more readable.</li>
185  </ul>
186
187  <p>Extract:</p>
188
189  <ul>
190    <li>The <code>ROOTDIR</code> part of the <code>RDEST::ROOTDIR</code>
191    declaration is now optional.</li>
192
193    <li>The <code>MIRROR</code> declaration is deprecated, and replaced by the
194    <code>RDEST::MIRROR_CMD</code> declaration.</li>
195
196    <li>The build configuration file generated by extract should no longer
197    contain hard coded paths - except for <code>USE</code> declarations and
198    those protected by the <code>BLD</code> prefix.</li>
199
200    <li>The <code>VERSION</code> declaration is deprecated, and replaced by the
201    <code>REVISION</code> declaration.</li>
202
203    <li>Added a new <code>REVMATCH</code> declaration for the extract
204    configuration file. If you specify a revision (other than HEAD) for a
205    branch, and this revision is not associated with a changeset for this
206    branch, the system will normally inform you of this discrepancy. By setting
207    <code>REVMATCH</code> to "true", however, the discrepancy will cause
208    extract to fail.</li>
209
210    <li>Extract used to fail if the same file is modified by two different
211    branches (compared with the base branch). It now attempts to merge the
212    changes using <code>diff3 -E -m</code>. It only fails if there are
213    unresolved conflicts.</li>
214
215    <li>Consequently, the <code>OVERRIDE</code> declaration is deprecated, and
216    replaced by the <code>CONFLICT</code> declaration, which can be set to
217    <samp>fail</samp>, <samp>merge</samp> (default) or
218    <samp>override</samp>.</li>
219  </ul>
220
221  <h2 id="fix">Minor enhancements &amp; Bug Fixes</h2>
222
223  <p>Build:</p>
224
225  <ul>
226    <li>If there is no source file to build, report an error at the beginning
227    of the build process.</li>
228  </ul>
229
230  <p>Code management commands:</p>
231
232  <ul>
233    <li>Fixed: FCM URL keyword not expanded when it is specified with an equal
234    sign in an option.</li>
235
236    <li>Fixed: typo in the output of <code>fcm branch --info</code>.</li>
237  </ul>
238
239  <p>Extract:</p>
240
241  <ul>
242    <li>Improved logic for better performance.</li>
243
244    <li>Allow mirroring to use <code>rsync</code> with an alternate remote
245    shell.</li>
246
247    <li><code>fcm cmp-ext-cfg</code>: Improved support for <a href=
248    "http://trac.edgewall.org/wiki/InterTrac">InterTrac</a> links.</li>
249  </ul>
250
251  <p>General:</p>
252
253  <ul>
254    <li>Fixed: problems parsing Subversion peg revision with the FCM URL
255    keywords.</li>
256
257    <li>The general shell used by FCM is changed from <code>/usr/bin/ksh</code>
258    to <code>/bin/sh</code> to improve portability.</li>
259
260    <li>Various other very minor enhancements and bug fixes.</li>
261  </ul>
262
263  <h2 id="issues">Known Issues</h2>
264
265  <p>The following are known issues with this release of FCM which we plan to
266  address in later releases:</p>
267
268  <ul>
269    <li>FCM build does not handle changes in an include file correctly in an
270    inherited build if the include file resides in the same directory as the
271    source file including it, and the source file remains unchanged. This is
272    due to the fact that most pre-processor/compiler commands search the
273    directory containing the source file for include files first before they
274    search elsewhere. We are hoping to find a solution to this problem before
275    the next release.</li>
276  </ul>
277
278  <h2 id="req">System Requirements</h2>
279
280  <h3 id="req_perl">Perl</h3>
281
282  <p>The core part of FCM is a set of Perl scripts and modules. For the build
283  system to work, you need the following modules installed:</p>
284
285  <ul>
286    <li>Carp</li>
287
288    <li>Cwd</li>
289
290    <li>File::Basename</li>
291
292    <li>File::Compare</li>
293
294    <li>File::Find</li>
295
296    <li>File::Path</li>
297
298    <li>File::Spec::Functions</li>
299
300    <li>File::Spec</li>
301
302    <li>FindBin</li>
303
304    <li>Getopt::Long</li>
305
306    <li>POSIX</li>
307  </ul>
308
309  <p>The code management commands and extract system need the following
310  additional modules installed:</p>
311
312  <ul>
313    <li>File::Temp</li>
314
315    <li>Getopt::Long</li>
316
317    <li>HTTP::Date</li>
318
319    <li>XML::DOM</li>
320  </ul>
321
322  <p>To use the simple GUI for some of the code management commands, you also
323  need the following modules:</p>
324
325  <ul>
326    <li>Tk::ROText</li>
327
328    <li>Tk</li>
329  </ul>
330
331  <p>At the Met Office we are currently using the complete FCM system with Perl
332  5.8.x. In addition the build system is being used with Perl 5.6.x.</p>
333
334  <h3 id="req_svn">Subversion</h3>
335
336  <p>To use the code management commands (and relevant parts of the extract
337  system) you need to have <a href=
338  "http://subversion.tigris.org/">Subversion</a> installed.</p>
339
340  <ul>
341    <li>FCM makes extensive use of peg revisions in both the code management
342    and extract systems. This requires Subversion 1.4.0.</li>
343
344    <li>At the Met Office we are currently using Subversion 1.4.3.</li>
345  </ul>
346
347  <p>Note that the extract system can mirror extracted code to a remote
348  platform for building. Therefore it is only necessary to have Subversion
349  installed on the platform where you do your code development. If you use
350  other platforms purely for building and running then you do not need to have
351  Subversion installed on these platforms.</p>
352
353  <h3 id="req_trac">Trac</h3>
354
355  <p>The use of <a href="http://trac.edgewall.org/">Trac</a> is entirely
356  optional (although highly recommended if you are using Subversion).</p>
357
358  <ul>
359    <li>The <code>--trac</code> and <code>--wiki</code> options to the
360    <code>fcm diff --branch</code> command allow you to view branch differences
361    using Trac. This requires Trac 0.10.</li>
362
363    <li>At the Met Office we are currently using Trac 0.10.3.</li>
364  </ul>
365
366  <h3 id="req_other">Other Requirements</h3>
367
368  <p>The <code>fcm conflicts</code> command requires <a href=
369  "http://furius.ca/xxdiff/">xxdiff</a>. At the Met Office we are currently
370  using version 3.1. The <code>fcm diff --graphical</code> command also uses
371  xxdiff by default although other graphical diff tools can also be used.</p>
372
373  <p>The extract system can use diff3, which is part of <a href=
374  "http://www.gnu.org/software/diffutils/">GNU diffutils</a>, to merge together
375  changes where the same file is modified by two different branches (compared
376  with the base branch). At the Met Office we are currently using version
377  2.8.1.</p>
378
379  <p>The build system requires <a href=
380  "http://www.gnu.org/software/make/make.html">GNU make</a>. At the Met Office
381  we are currently using version 3.79.x and 3.80.</p>
382
383  <p>Optionally, the build system can use <a href=
384  "http://www.ifremer.fr/ditigo/molagnon/fortran90/">f90aib</a> to generate
385  interface files. However, there is also a built in Perl based interface file
386  generator which is quicker and better in most cases so you are unlikely to
387  need f90aib unless you hit a problem with some particular code.</p>
388
389  <p>FCM is intended to run on a Unix/Linux system. It is currently used at the
390  Met Office on Linux (Red Hat Enterprise 2.1 and 4.5) and HP-UX 11.00.</p>
391
392  <h2 id="ins">Installation</h2>
393
394  <p>FCM is distributed in the form of a compressed tar file. Un-pack the tar
395  file into an appropriate location on your system. Then add the
396  <samp>bin/</samp> directory into your <var>PATH</var>. Once you have done
397  this you should now have full access to the FCM system, assuming that you
398  have met the requirements described in the previous section.</p>
399
400  <p>If you wish to define keywords for your systems you will need to create a
401  file <samp>etc/fcm.cfg</samp>. An example file, <samp>fcm.cfg.eg</samp>, is
402  provided which is a copy of the file currently used at the Met Office. For
403  further details please refer to the section <a href=
404  "../user_guide/system_admin.html#fcm-keywords">FCM keywords</a> in the System
405  Admin chapter of the User Guide.</p>
406
407  <p>The <samp>doc/</samp> directory contains all the system documentation.</p>
408
409  <ul>
410    <li><samp>doc/release_notes/</samp> contains these release notes. It also
411    contains the release notes for all previous versions which may be useful if
412    you have skipped any versions.</li>
413
414    <li><samp>doc/user_guide/</samp> contains the <a href="../user_guide/">FCM
415    User Guide</a>.</li>
416
417    <li><samp>doc/design/</samp> contains the <a href="../design/">FCM Detailed
418    Design</a> document (currently in draft form).</li>
419
420    <li><samp>doc/standards/</samp> contains the FCM <a href=
421    "../standards/perl_standard.html">Perl</a> and <a href=
422    "../standards/fortran_standard.html">Fortran</a> coding standards. The Perl
423    standard describes the standards followed by the FCM code. The Fortran
424    standard contains some <a href=
425    "../standards/fortran_standard.html#fcm">specific advice</a> on the best
426    way of writing Fortran code for use with FCM as well as more general advice
427    on good practise.</li>
428
429    <li><samp>doc/collaboration/</samp> contains the <a href=
430    "../collaboration/index.html">External Distribution &amp; Collaboration for
431    FCM Projects</a> document which discusses how projects configured under FCM
432    can be distributed externally.</li>
433  </ul>
434
435  <p>The <samp>tutorial/</samp> directory contains the files necessary to set
436  up a tutorial repository. This will allow you to follow the <a href=
437  "../user_guide/getting_started.html#tutorial">tutorial section</a> in the
438  User Guide.</p>
439
440  <ul>
441    <li>The file <samp>tutorial/repos/tutorial.dump</samp> should be loaded
442    into an empty repository using the <code>svnadmin load</code> command.</li>
443
444    <li>The hook scripts in <samp>tutorial/hook/</samp> should then be
445    installed in this repository in order to prevent any commits to the trunk.
446    Note that the configuration file <samp>svnperms.conf</samp> assumes that
447    the tutorial repository is called <samp>tutorial_svn</samp>. Please edit
448    this file if you use a different name. You also need to install the
449    Subversion utility <code>svnperms.py</code> in order for this to work.</li>
450
451    <li>The repository should be configured to allow users write access. You
452    may find it easiest to simply allow anonymous access.</li>
453
454    <li>A Trac system should be configured associated with the Tutorial
455    repository. You then need to allow users write access. You may find it
456    easiest to set up a number of guest accounts for this purpose.</li>
457  </ul>
458
459  <p>The <samp>templates/</samp> directory contains various example scripts
460  which you may find useful. Note that these scripts are all specific to the
461  Met Office and may contain hard coded paths and email addresses. They are
462  provided in the hope that you may find them useful as templates for setting
463  up similar scripts of your own. However, they should only be used after
464  careful review to adapt them to your environment. The contents are as
465  follows:</p>
466
467  <dl>
468    <dt>templates/hook/pre-commit</dt>
469
470    <dd>
471      This script restricts write-access to the repository by checking the
472      following:
473
474      <ul>
475        <li>It executes the Subversion utility <code>svnperms.py</code> if it,
476        and the associated <code>svnperms.conf</code> file, exist. This utility
477        checks whether the author of the current transaction has enough
478        permission to write to particular paths in the repository.</li>
479
480        <li>It checks the disk space required by the current transaction. It
481        fails the commit if it requires more than 5Mb of disk space.</li>
482      </ul>
483    </dd>
484
485    <dt>templates/hook/post-commit</dt>
486
487    <dd>A simple post-commit hook script which runs the script
488    <code>post-commit-background</code> in the background.</dd>
489
490    <dt>templates/hook/post-commit-background</dt>
491
492    <dd>
493      This script runs in the background after each commit
494
495      <ul>
496        <li>It updates a <code>&lt;repos&gt;.latest</code> file with the latest
497        revision number.</li>
498
499        <li>It creates a dump of the new revision.</li>
500
501        <li>It calls the script <code>background_updates.pl</code> if it
502        exists.</li>
503      </ul>This script is installed as standard in all our repositories.
504    </dd>
505
506    <dt>templates/hook/background_updates.pl</dt>
507
508    <dd>An example of how you may want to set up a
509    <code>background_updates.pl</code> script to perform post-commit tasks for
510    a specific repository. This script uses a lock file to prevent multiple
511    commits in quick succession from causing problems.</dd>
512
513    <dt>templates/hook/pre-revprop-change</dt>
514
515    <dd>A simple pre-revprop-change hook script which runs the script
516    <code>pre-revprop-change.pl</code>.</dd>
517
518    <dt>templates/hook/pre-revprop-change.pl</dt>
519
520    <dd>If a user attempts to modify the log message of a changeset and he/she
521    is not the original author of the changeset, this script will e-mail the
522    original author. You can also set up a watch facility to monitor changes of
523    log messages that affect particular paths in the repository. For further
524    details please refer to the section <a href=
525    "../user_guide/system_admin.html#svn_watch">Watching changes in log
526    messages</a> in the System Admin chapter of the User Guide.</dd>
527
528    <dt>templates/hook/post-revprop-change</dt>
529
530    <dd>A simple post-revprop-change hook script which runs the script
531    <code>post-revprop-change.py</code>.</dd>
532
533    <dt>templates/hook/post-revprop-change.py</dt>
534
535    <dd>This hook script updates the Trac SQLite database following a
536    successful change in the log message.</dd>
537
538    <dt>templates/utils/cron_template.sh</dt>
539
540    <dd>An example of how you might set up a cron job to make use of the
541    <samp>&lt;repos&gt;.latest</samp> file.</dd>
542
543    <dt>templates/utils/daily_cron</dt>
544
545    <dd>The cron job which we run each night. It verifies and backs up each of
546    our repositories, housekeeps the revision dumps created by
547    <code>post-commit-background</code> and backs up each of our Trac systems.
548    It also handles the distribution of FCM to various platforms at the Met
549    Office.</dd>
550
551    <dt>templates/utils/fcm_add_trac.pl</dt>
552
553    <dd>This script sets up a new Trac system and applies some configuration
554    options which we use by default at the Met Office.</dd>
555
556    <dt>templates/utils/recover_svn.pl</dt>
557
558    <dd>This script allows us to recover all of our Subversion repositories by
559    using the nightly backups and the repository dumps.</dd>
560  </dl>
561</body>
562</html>
Note: See TracBrowser for help on using the repository browser.