source: LMDZ6/branches/Amaury_dev/tools/fcm/doc/release_notes/1-3.html

Last change on this file was 5129, checked in by abarral, 6 months ago

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