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.
getting_started.html in vendors/doc/user_guide – NEMO

source: vendors/doc/user_guide/getting_started.html @ 10669

Last change on this file since 10669 was 10669, checked in by nicolasmartin, 5 years ago

Import latest FCM release from Github into the repository for testing
File size: 57.8 KB
Line 
1<!DOCTYPE html>
2<html>
3<head>
4  <title>FCM: User Guide: Getting Started</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 class="active" href="#">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: User Guide: Getting Started</h1>
31  </div>
32
33  <div class="container">
34  <div class="row">
35  <div class="col-md-12">
36
37  <h2 id="introduction">Introduction</h2>
38
39  <p>This chapter takes a <em>hands-on</em> approach to help you set up your
40  FCM session, and familiarise yourself with some of the system's basic
41  concepts and working practices. It is designed to complement other sections
42  of the User Guide.</p>
43
44  <p>You may also find it useful to refer to the <a href=
45  "annex_quick_ref.html">Annex: Quick reference</a>.</p>
46
47  <h2 id="setup">How to set yourself up to run FCM</h2>
48
49  <p>It is easy to set yourself up to run FCM. Simply follow the steps
50  below:</p>
51
52  <dl>
53    <dt>Installation</dt>
54
55    <dd>If FCM is not yet installed at your site, please refer to the <a href=
56    "../installation/">FCM: Installation</a> for detail.</dd>
57
58    <dt>Configure your editor for Subversion</dt>
59
60    <dd>
61      <p>When you attempt to create a branch or commit changes to the
62      repository, you will normally be prompted to edit your commit log message
63      using a text editor. The order of priority for determining the editor
64      command (where lower-numbered locations take precedence over
65      higher-numbered locations) is:</p>
66
67      <ol>
68        <li>environment variable <var>SVN_EDITOR</var></li>
69
70        <li>the <var>editor-cmd</var> option in the <var>[helpers]</var>
71        section of the user's <samp>$HOME/.subversion/config</samp> file.</li>
72
73        <li>environment variable <var>VISUAL</var></li>
74
75        <li>environment variable <var>EDITOR</var></li>
76
77        <li>default to <code>vi</code> (or <code>gvim</code> when running the
78        FCM GUI)</li>
79      </ol>
80
81      <p>It is worth bearing in mind that an editor must be able to run in the
82      foreground. For example, you can add one of the followings in your
83      <samp>$HOME/.kshrc</samp> (ksh) or <samp>$HOME/.bashrc</samp> (bash):</p>
84      <pre>
85# GVim
86export SVN_EDITOR='gvim -f'
87
88# Emacs
89export SVN_EDITOR=emacs
90
91# Kate
92export SVN_EDITOR=kate
93</pre>
94    </dd>
95
96    <dt>Configure your e-mail address in Trac</dt>
97
98    <dd>
99      <p>Trac can be configured to send automatic e-mail notifications to
100      authors of any ticket whenever there are changes to that ticket (and we
101      would expect most systems to be configured in this way). You should check
102      that the settings for your name and e-mail address are correct. To do
103      this you need to go to the Settings page once you are logged into Trac.
104      (Click on <kbd>Settings</kbd> just above the menu bar). Check that your
105      settings are entered correctly.</p>
106    </dd>
107
108    <dt>Configure your web browser</dt>
109
110    <dd>
111      <p>FCM assumes that <code>firefox</code> is the command to invoke your
112      default web browser. If you use another web browser, you should configure
113      it in your <samp>$HOME/.metomi/fcm/external.cfg</samp> file. See the
114      section on <a href="command_ref.html#fcm-browse">fcm browse</a> for
115      further information.</p>
116    </dd>
117  </dl>
118
119  <h2 id="tutorial">Tutorial</h2>
120
121  <h3 id="tutorial_intro">Introduction</h3>
122
123  <p>This tutorial leads you through the basics of using FCM to make changes to
124  your source code, and demonstrates the recommended practices for working with
125  it. A tutorial Subversion repository, with its own Trac system, is available
126  for you to practice for working with the FCM system. You will work through
127  the following activities:</p>
128
129  <ul>
130    <li><a href="#tutorial_create-ticket">Create a new ticket</a></li>
131
132    <li><a href="#tutorial_create-branch">Create a branch</a></li>
133
134    <li><a href="#tutorial_checkout">Checkout a working copy</a></li>
135
136    <li><a href="#tutorial_change">Make changes to files in your working
137    copy</a></li>
138
139    <li><a href="#tutorial_commit">Commit your changes to the
140    repository</a></li>
141
142    <li><a href="#tutorial_extract">Test your changes</a></li>
143
144    <li><a href="#tutorial_merge">Merge changes from the trunk and resolve
145    conflicts</a></li>
146
147    <li><a href="#tutorial_review-ticket">Review changes</a></li>
148
149    <li><a href="#tutorial_merge-back">Commit to the trunk</a></li>
150
151    <li><a href="#tutorial_extra-extract">Extra activities on the extract and
152    build systems</a></li>
153
154    <li><a href="#tutorial_delete-branch">Delete your branch</a></li>
155
156    <li><a href="#tutorial_delete-final-comments">Final comments</a></li>
157  </ul>
158
159  <p>We recommend that you create a work area in your filespace, for example,
160  <samp>$HOME/tutorial/work</samp> for your working copy, and
161  <samp>$HOME/tutorial/test</samp> for your build test.</p>
162
163  <p>If you have not already done so, you should set up your desktop
164  environment as described above in the <a href="#setup">How to set yourself up
165  to run FCM</a> section.</p>
166
167  <p>It is also worth knowing that the <a href=
168  "http://svnbook.red-bean.com/en/1.8/">Subversion Book</a> is a great source
169  of reference of Subversion features. In particular, the <a href=
170  "http://svnbook.red-bean.com/en/1.8/svn.basic.html">Fundamental Concepts</a>
171  and <a href="http://svnbook.red-bean.com/en/1.8/svn.tour.html">Basic
172  Usage</a> chapters are well worth reading.</p>
173
174  <h3 id="tutorial_create-ticket">Create a new ticket</h3>
175
176  <p><em>Trac is an integrated web-based issue tracker and wiki system. You
177  will use it to manage and keep track of changes in your project. The issue
178  tracker is called the ticket system. When you want to report a problem or
179  submit a change request, you will create a new ticket. In a typical
180  situation, you and/or your colleagues will make changes to your system in
181  order to resolve the problem or change request, and you will monitor these
182  changes via the ticket.</em></p>
183
184  <p>After completing this sub-section, you will learn how to:</p>
185
186  <ul>
187    <li>launch a Trac system,</li>
188
189    <li>create a new Trac ticket,</li>
190
191    <li>search for a Trac ticket, and</li>
192
193    <li>accept a Trac ticket.</li>
194  </ul>
195
196  <p>Further reading:</p>
197
198  <ul>
199    <li><a href="overview.html">System Overview</a></li>
200
201    <li>Code Management System &gt; <a href=
202    "code_management.html#svn_basic">Basic Command Line Usage</a></li>
203
204    <li>Code Management System &gt; <a href="code_management.html#trac">Using
205    Trac</a></li>
206
207    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm-browse">fcm
208    browse</a></li>
209  </ul>
210
211  <h4>Launch a Trac system</h4>
212
213  <p>To launch the Trac system for the tutorial: type and <kbd>Enter</kbd> the
214  following command:</p>
215  <pre>
216(SHELL PROMPT)$ fcm browse fcm:tutorial
217</pre>
218
219  <p>This is probably the first time you have used the <code>fcm</code>
220  command. The command has the general syntax:</p>
221  <pre>
222fcm &lt;sub-command&gt; [&lt;options...&gt;] &lt;arguments&gt;
223</pre>
224
225  <p>For example, if you type <code>fcm help</code>, it will display a listing
226  of what sub-commands are available, and if you type <code>fcm help
227  &lt;sub-command&gt;</code>, it will display help for that particular
228  sub-command.</p>
229
230  <p>The <code>trac</code> sub-command launches the corresponding Trac system
231  browser for a Subversion URL specified in your argument. In this case, we are
232  asking it to display the Trac system browser for the tutorial. The argument
233  <samp>fcm:tutorial</samp> is a FCM URL keyword and will be expanded by FCM
234  into a real Subversion URL (e.g.
235  <samp>svn://fcm1/tutorial_svn/tutorial</samp>). You are encouraged to use FCM
236  URL keywords throughout the tutorial, as it will save you a lot of
237  typing.</p>
238
239  <p>Note: Although we use the Trac system as a browser for a Subversion
240  repository, they do not interact in any other ways. Having access to a Trac
241  system does not guarantee the same privilege to a Subversion repository. In
242  particular, you should note the differences between the URLs of a Subversion
243  repository path and its equivalence in a Trac browser.</p>
244
245  <p>There are other ways to launch the Trac system for a project. If you know
246  its URL, you can launch the Trac system by entering it in the address box of
247  your favourite browser. If you often access a Trac system for a particular
248  project, you should bookmark it in your favourite browser.</p>
249
250  <h4>Create a new Trac ticket</h4>
251
252  <p>Click on <kbd>Login</kbd> just above the menu bar, enter your Unix/Linux
253  user ID as your user name and leave the password empty. Then click on
254  <kbd>OK</kbd> to proceed.</p>
255
256  <p>Once you have logged in, the <kbd>New Ticket</kbd> link will become
257  available on the menu bar. Click on it to display a new ticket form, where
258  you can enter details about your problem or change request. In the tutorial,
259  it does not matter what you enter, but you should feel free to play around
260  with wiki formatting when entering the <em>Full description</em>. (Click on
261  <kbd>WikiFormatting</kbd> to see how you can use it.) For example:</p>
262
263  <ul>
264    <li>Short summary:
265      <pre>
266Tutorial to change repository files and resolve conflicts with the trunk
267</pre>
268    </li>
269
270    <li>Full description:
271      <pre>
272In this tutorial, I shall:
273 1. use FCM commands
274 2. play with WikiFormatting in Trac tickets     
275 3. create a branch and checkout a working copy
276 4. make changes to files in it
277 5. commit my changes and assign the ticket for review
278 6. record the review and assign the ticket back to the author
279 7. merge in the trunk, and resolve any conflicts
280 8. merge my changes back to the trunk
281 9. close the ticket
282 10. delete my branch
283</pre>
284    </li>
285
286    <li>Feel free to select an option you desire for each of the other ticket
287    properties: Type, Component, Priority, Version and Milestone.</li>
288  </ul>
289
290  <p>At the bottom of the page, click the <kbd>Preview</kbd> button to see what
291  the description would look like. When you are happy, click the <kbd>Submit
292  changes</kbd> button. Trac will create the new ticket and return it in a
293  state where you can append to it.</p>
294
295  <p>When the ticket is created, you should get an automatic e-mail notication
296  from the Trac system. In real life, depending on the setting, the owner of
297  your Trac system may also get a similar e-mail notification. It is worth
298  noting that each time the ticket is modified, the Trac system will send out
299  an e-mail notification to you (the reporter) and anyone who modified the
300  ticket subsequently.</p>
301
302  <h4>Search for a Trac ticket</h4>
303
304  <p>You should remember the number of your new ticket, as you will have to
305  revisit it later.</p>
306
307  <p>In real work, it is often not practical to have to remember the numbers of
308  all the tickets you have created. Trac provides a powerful custom query for
309  searching a ticket. You can search for the ticket you have just created by
310  clicking the <kbd>View Tickets</kbd> link. Feel free to play with the custom
311  query tool. Add or remove filters and try grouping your results by different
312  categories.</p>
313
314  <p>In addition, you can search your ticket using the keyword
315  <kbd>Search</kbd> utility at the top right hand corner of each Trac page. (If
316  you enter <kbd>#&lt;number&gt;</kbd> in the search box, it will take you
317  directly to that ticket.) In the tutorial, however, it may be easiest if you
318  simply leave the tutorial Trac system open, so that you do not have to login
319  again when you come back to your ticket.</p>
320
321  <h4>Start work on your Trac ticket</h4>
322
323  <p>The status of the ticket is <em>new</em>. When you start working on a
324  problem reported in a ticket it is good practice to change the status to
325  <em>in_progress</em> to indicate that you are working on it. For the purpose
326  of the tutorial, however, this is entirely optional since you know you will
327  be doing all the work any way.</p>
328
329  <p>To start work on a ticket, click on <kbd>start work</kbd> in the
330  <em>Action</em> box at the bottom of the page, and then click on <kbd>Submit
331  changes</kbd>.</p>
332
333  <h3 id="tutorial_create-branch">Create a branch</h3>
334
335  <p><em>You create a branch by making a copy of your project at a particular
336  revision. Most often, this will be a particular revision of the trunk, i.e.
337  the main branch/development line in your project. A branch resides in the
338  repository. It allows you to work in parallel with your colleagues without
339  affecting one another, while keeping your changes under version
340  control.</em></p>
341
342  <p>After completing this sub-section, you will learn how to:</p>
343
344  <ul>
345    <li>create a branch in a Subversion repository, and</li>
346
347    <li>update a ticket with a link to a branch.</li>
348  </ul>
349
350  <p>Further reading:</p>
351
352  <ul>
353    <li>Code Management System &gt; Branching &amp; Merging &gt; <a href=
354    "code_management.html#svn_branching_create">Creating Branches</a></li>
355
356    <li>Code Management Working Practices &gt; <a href=
357    "working_practices.html#branching">Branching &amp; Merging</a></li>
358
359    <li>FCM Command Reference &gt; <a href=
360    "command_ref.html#fcm-branch-create">fcm branch-create</a></li>
361  </ul>
362
363  <h4>Create a branch in a Subversion repository</h4>
364
365  <p><strong>Important note: please ensure that your branch is created from
366  revision 1 of the trunk here, or the tutorial on merge will fail to work
367  later.</strong></p>
368
369  <p><dfn>Command line</dfn>: issue the <code>fcm branch-create [-rREV] TICKET
370  URL-PROJECT</code> command. (Note: you can write <code>fcm
371  branch-create</code> as <code>fcm bcreate</code> or even <code>fcm
372  bc</code>.) E.g. if your ticket number is <samp>#133</samp>:</p>
373  <pre>
374(SHELL PROMPT)$ fcm bc 133 fcm:tutorial@1
375</pre>
376
377  <p>You will be prompted to edit the message log file. A standard template is
378  automatically supplied for the commit. However, if you want to add extra
379  comment for the branch, please do so <strong>above</strong> the line that
380  says <samp>--Add your commit message ABOVE - do not alter this line or those
381  below--</samp>. When you are ready, save your change and exit the editor.
382  Answer <kbd>Yes</kbd> when you are prompted to go ahead and create the
383  branch.</p>
384
385  <p>Note: Subversion will prompt you for a password the first time you access
386  a repository. The password will normally be cached by the client, and you
387  will not have to specify a password on subsequent access.</p>
388
389  <p>When creating branches for the first time, you will notice that FCM will
390  create and commit any missing sub-directories it needs to set up your branch
391  inside the repository, before creating your branch and commiting it.</p>
392
393  <p>Take a note of the revision number the branch was created at, and its
394  branch name. (The revision number is the number following the last output
395  that says "Committed revision". In the example above, the branch created at
396  <samp>r811</samp> is called <samp>branches/dev/matt/r1_133</samp>, which is a
397  branch of the <samp>tutorial</samp> project in the
398  <samp>svn://fcm1/tutorial_svn</samp> repository.)</p>
399
400  <h4>Update your ticket with a link to your branch</h4>
401
402  <p>If you wish, you can update your ticket with details of the branch. Note
403  that this step is entirely optional. It is useful for developments which will
404  take a long time to complete. For short lived branches, this step is probably
405  unnecessary.</p>
406
407  <p>In the ticket you have created, refer to the revision number in the
408  <kbd>Add/Change</kbd> box, for example:</p>
409  <pre>
410r811: created source:tutorial/branches/dev/matt/r1_133@811.
411</pre>
412
413  <p>Note:</p>
414
415  <ul>
416    <li><samp>source:tutorial/branches/dev/matt/r1_133@811</samp> is a Trac
417    wiki link. In this syntax, you do not have to put in the root URL, (e.g.
418    <samp>svn://fcm1/tutorial_svn/</samp>), but you should specify your branch
419    using the project name (<samp>tutorial</samp>), the branch name
420    (<samp>branches/dev/matt/r1_133</samp>), and a revision number. Trac will
421    translate this into a link to that branch.</li>
422
423    <li>Trac will translate the syntax <code>r&lt;number&gt;</code> or
424    <code>[&lt;number&gt;]</code> into a link to the numbered changeset.</li>
425  </ul>
426
427  <p>Click on <kbd>Preview</kbd> and check that the links work correctly, and
428  on <kbd>Submit changes</kbd> when you are ready.</p>
429
430  <h3 id="tutorial_checkout">Checkout a working copy</h3>
431
432  <p><em>A Subversion working copy is an ordinary directory tree on your local
433  system, containing a collection of files. It is your private working area in
434  which you can make changes before publishing them back to the repository. You
435  create a working copy by using the checkout command on some subtree of the
436  repository.</em></p>
437
438  <p>After completing this sub-section, you will learn how to:</p>
439
440  <ul>
441    <li>checkout a Subversion working copy.</li>
442  </ul>
443
444  <p>Further reading:</p>
445
446  <ul>
447    <li>Code Management System &gt; <a href=
448    "code_management.html#svn_concepts">Basic Concepts</a></li>
449
450    <li>FCM Command Reference &gt; <a href="command_ref.html#svn">Other
451    Subversion Commands</a></li>
452  </ul>
453
454  <h4>Checkout a Subversion working copy</h4>
455
456  <p><dfn>Command line</dfn>: issue the <code>fcm checkout</code> (or simply
457  <code>fcm co</code>) command. E.g.:</p>
458  <pre>
459(SHELL PROMPT)$ fcm checkout fcm:tutorial_br/dev/matt/r1_133 tutorial
460</pre>
461
462  <ul>
463    <li>In the example, we have replaced the leading part of the Subversion URL
464    <samp>svn://fcm1/tutorial_svn/tutorial/branches</samp> with the FCM URL
465    keyword <samp>fcm:tutorial_br</samp>. This is mainly to save you from
466    having to type in the full URL. However, you may find it easier to
467    copy-and-paste the full Subversion URL from the output generated when you
468    created the branch.</li>
469
470    <li>In the above command, we have asked the system to create a working copy
471    in <samp>$PWD/tutorial</samp>. If you do not specify a local directory
472    <var>PATH</var> in the <code>checkout</code> command, it will create a
473    working copy in the current working directory, using the basename of the
474    URL. For example, when you checkout the branch you have just created, the
475    command would create the working copy in <samp>$PWD/r1_133</samp>, which is
476    often undesirable. Make a note of the location of your working copy, in
477    case you forget where you have put it.</li>
478
479    <li>If you do not specify a revision to checkout, it will checkout the
480    HEAD, i.e. the latest, revision.</li>
481  </ul>
482
483  <p>Example:</p>
484  <pre>
485=&gt; fcm checkout fcm:tutorial_br/dev/matt/r1_133 tutorial
486A    tutorial/doc
487A    tutorial/doc/hello.html
488A    tutorial/src
489A    tutorial/src/subroutine
490A    tutorial/src/subroutine/hello_c.c
491A    tutorial/src/subroutine/hello_sub.f90
492A    tutorial/src/module
493A    tutorial/src/module/hello_num.f90
494A    tutorial/src/module/hello_constants.f90
495A    tutorial/src/program
496A    tutorial/src/program/hello.f90
497A    tutorial/fcm-make.cfg
498Checked out revision 811.
499</pre>
500
501  <h3 id="tutorial_change">Make changes to files in your working copy</h3>
502
503  <p><em>Subversion provides various useful commands to help you monitor your
504  working copy. The most useful ones are "diff", "revert" and "status". You
505  will also find "add", "copy", "delete" and "move" useful when you are
506  rearranging your files and directories.</em></p>
507
508  <p>After completing this sub-section, you will learn how to:</p>
509
510  <ul>
511    <li>make and revert changes,</li>
512
513    <li>add and remove files,</li>
514
515    <li>inspect the status of a working copy, and</li>
516
517    <li>display changes in a working copy.</li>
518  </ul>
519
520  <p>Further reading:</p>
521
522  <ul>
523    <li>Code Management System &gt; <a href=
524    "code_management.html#svn_basic">Basic Command Line Usage</a></li>
525
526    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm-add">fcm
527    add</a>, <a href="command_ref.html#fcm-diff">fcm diff</a>, <a href=
528    "command_ref.html#fcm-delete">fcm delete</a>, <a href=
529    "command_ref.html#svn">Other Subversion Commands</a></li>
530  </ul>
531
532  <h4>Make and revert changes</h4>
533
534  <p>For the later part of the tutorial to work, you must make the following
535  modifications:</p>
536
537  <ul>
538    <li>Change to the <samp>src/module/</samp> sub-directory in your working
539    copy.</li>
540
541    <li>Edit <samp>hello_constants.f90</samp>, using your favourite editor, and
542    change: <samp>Hello World!</samp> to <kbd>Hello Earthlings!</kbd>. Save
543    your change and exit the editor.</li>
544
545    <li>Edit <samp>hello_num.f90</samp> and either add a comment, or make a
546    minor code change - for example, use one of :
547      <pre>
548!This will print a really really big integer.
549WRITE(*, *) "Sadly, there's no encoding for Martian base-60"
550</pre>
551    </li>
552  </ul>
553
554  <p>Try the following so that you know how to restore a changed file:</p>
555
556  <ul>
557    <li>Change to the <samp>src/subroutine/</samp> directory of your working
558    copy.</li>
559
560    <li>Make a change in file <b>hello_c.c</b>, using your favourite
561    editor.</li>
562
563    <li>To see that you have <strong>M</strong>odified this file: issue the
564    <code>fcm status</code> command</li>
565
566    <li>Run the <code>revert</code> command to get the file back unmodified:
567      <pre>
568(SHELL PROMPT)$ fcm revert hello_c.c
569</pre>
570    </li>
571  </ul>
572
573  <h4>Add and remove files</h4>
574
575  <p>You may also want to try the following FCM commands in your
576  <samp>doc/</samp> sub-directory. You can safely make changes here since they
577  will not interfere with your code changes.</p>
578
579  <ul>
580    <li>change to the <samp>doc/</samp> directory of your working copy.</li>
581
582    <li>Echo some text into a new file and then run the <code>add</code>
583    command, which lets the repository know you're adding a new file at the
584    next commit. For example:
585      <pre>
586(SHELL PROMPT)$ echo 'Some text' &gt;new_file.txt
587(SHELL PROMPT)$ fcm add new_file.txt
588</pre>
589    </li>
590
591    <li>Make a copy of <samp>hello.html</samp> and remove the original, using
592    the <code>copy</code> and <code>delete</code> commands. For example:
593      <pre>
594(SHELL PROMPT)$ fcm copy hello.html add.html
595(SHELL PROMPT)$ fcm delete hello.html
596</pre>
597    </li>
598
599    <li>You can use a simple <code>move</code> sub-command for the above
600    <code>copy</code> and <code>delete</code>.</li>
601  </ul>
602
603  <h4>Inspect the status of a working copy</h4>
604
605  <p>Change to the root directory of your working copy.</p>
606
607  <p><dfn>Command line</dfn>: issue the <code>fcm status</code> (or simply
608  <code>fcm st</code>) command.</p>
609
610  <p>Example:</p>
611  <pre>
612=&gt; fcm status
613D      doc/hello.html
614A      doc/new_file.txt
615A  +   doc/add.html
616M      src/module/hello_num.f90
617M      src/module/hello_constants.f90
618</pre>
619
620  <p>This confirms the actions you have taken. You have
621  <strong>D</strong>eleted a file, <strong>A</strong>dded a new file,
622  <strong>A</strong>dded a file with history (<strong>+</strong>) and
623  <strong>M</strong>odified two others. It also confirms the action of the
624  <code>revert</code> command.</p>
625
626  <h4>Display changes in a working copy</h4>
627
628  <p>You can view the changes you have made to your working copy.</p>
629
630  <p><dfn>Command line</dfn>: issue the <code>fcm diff --graphical</code> (or
631  simply <code>fcm di -g</code>) command.</p>
632
633  <p>A listing of the files you have changed will be displayed, and a graphical
634  diff tool will open up for each modified file.</p>
635
636  <h3 id="tutorial_commit">Commit your changes to the repository</h3>
637
638  <p><em>The change in your working copy remains local until you commit it to
639  the repository where it becomes permanent. If you are planning to make a
640  large number of changes, you are encouraged to commit regularly to your
641  branch at appropriate intervals.</em></p>
642
643  <p>After completing this sub-section, you will learn how to:</p>
644
645  <ul>
646    <li>commit your changes, and</li>
647
648    <li>inspect your changes using Trac.</li>
649  </ul>
650
651  <p>Further reading:</p>
652
653  <ul>
654    <li>Code Management System &gt; <a href=
655    "code_management.html#svn_basic">Basic Command Line Usage</a></li>
656
657    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm-commit">fcm
658    commit</a></li>
659  </ul>
660
661  <h4>Commit changes</h4>
662
663  <p><dfn>Command line</dfn>: issue the <code>fcm commit</code> (or simply
664  <code>fcm ci</code>) command.</p>
665
666  <p>A text editor will appear to allow you to edit the commit message. You
667  must add a commit message to describe your change <strong>above</strong> the
668  line that says <samp>--Add your commit message ABOVE - do not alter this line
669  or those below--</samp>. (A suggestion is given as the highlighted text in
670  the example below.) Your commit will fail if you do not enter a commit
671  message.</p>
672
673  <p>Save your change and exit the editor. Answer <kbd>Yes</kbd> when you are
674  prompted to confirm the commit. For example:</p>
675  <pre>
676[info] gvim -f: starting commit message editor...
677Change summary:
678--------------------------------------------------------------------------------
679[Project: tutorial]
680[Branch : branches/dev/matt/r1_133]
681[Sub-dir: &lt;top&gt;]
682
683D       doc/hello.html
684A       doc/new_file.txt
685A  +    doc/add.html
686M       src/module/hello_num.f90
687M       src/module/hello_constants.f90
688--------------------------------------------------------------------------------
689Commit message is as follows:
690--------------------------------------------------------------------------------
691#133: tutorial is fun.
692--------------------------------------------------------------------------------
693Would you like to commit this change?
694Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
695Adding         doc/add.html
696Deleting       doc/hello.html
697Adding         doc/new_file.txt
698Sending        src/module/hello_constants.f90
699Sending        src/module/hello_num.f90
700Transmitting file data ...
701Committed revision 812.
702=&gt; svn update
703At revision 812.
704</pre>
705
706  <h4>Inspect changes using Trac</h4>
707
708  <p>Click on <kbd>Timeline</kbd> in Trac. Drill down to your changeset and see
709  how it appears. (Alternatively, if you enter <samp>r&lt;number&gt;</samp>
710  into the search box at the top right, it will take you directly to the
711  numbered changeset.)</p>
712
713  <p>Note:</p>
714
715  <ul>
716    <li>Wiki Formatting, used in the commit message, has customised the
717    changeset message.</li>
718
719    <li>All your changes are listed.</li>
720  </ul>
721
722  <h3 id="tutorial_extract">Test your changes</h3>
723
724  <p><em>You should test the changes in your branch before asking a colleague
725  to review them. FCM features a build system that allows you to build your
726  code easily. As your changes may be located in a repository branch and/or a
727  working copy, you should work with the extract system to extract the correct
728  code to build. The extract system allows you to extract code from the
729  repository, combining changes in different branches and your working copy,
730  before generating a configuration file and a suitable source tree for feeding
731  into the build system.</em></p>
732
733  <p><em>In this sub-section of the tutorial, you will be shown how to extract
734  and build the code from your branch. (There are some <a href=
735  "#tutorial_extra-extract">extra activities on the extract and build
736  systems</a> in a later sub-section of the tutorial should you want to explore
737  the extract and build systems in more depth.) In the example here, the
738  extract and build systems will be shown to you in their simplest form. In
739  real life, the managers of the systems you are developing code for will
740  provide you with more information on how to extract and build their
741  systems.</em></p>
742
743  <p>After completing this sub-section, you will learn how to:</p>
744
745  <ul>
746    <li>set up a simple FCM make configuration file for extract and build,
747    and</li>
748
749    <li>use the <a href="make.html">FCM Make</a> system to perform simple
750    extracts and builds.</li>
751  </ul>
752
753  <p>Further reading:</p>
754
755  <ul>
756    <li><a href="make.html">FCM Make</a></li>
757  </ul>
758
759  <p>You should extract and build your code in a different directory to your
760  working copy. For example, you may want to create a sub-directory
761  <samp>$HOME/tutorial/test/</samp> and change to it:</p>
762  <pre>
763(SHELL PROMPT)$ mkdir -p $HOME/tutorial/test
764(SHELL PROMPT)$ cd $HOME/tutorial/test
765</pre>
766
767  <h4>Set up a FCM make configuration file</h4>
768
769  <p>To set up a FCM make configuration file from scratch, launch your
770  favourite editor and add the following lines:</p>
771  <pre>
772steps = extract build
773extract.ns = tutorial
774extract.location[tutorial] = branches/dev/$LOGNAME/r1_133
775extract.path-root[tutorial] = src
776build.target{task} = link
777</pre>
778
779  <p>Note:</p>
780
781  <ul>
782    <li>The <code><a href=
783    "annex_cfg.html#make.extract.location">extract.location</a></code>
784    declaration is set to <samp>branches/dev/$LOGNAME/r1_133</samp>. If you
785    have named your branch differently, you should modify the right hand side
786    of the declaration.</li>
787
788    <li>The build system uses <code>gfortran</code> and <code>gcc</code> as the
789    default Fortran and C (respectively) compilers. If you do not have these
790    compilers installed on your system, you can configure your Fortran and C
791    compilers using the <code><a href=
792    "annex_cfg.html#make.build.prop.fc">build.prop{fc}</a></code> and
793    <code><a href="annex_cfg.html#make.build.prop.cc">build.prop{cc}</a></code>
794    declarations.</li>
795  </ul>
796
797  <p>Save the file as <samp>fcm-make.cfg</samp> and exit your editor.</p>
798
799  <h4>Perform an extract and a build</h4>
800
801  <p>Issue the command <code><a href="command_ref.html#fcm-make">fcm
802  make</a></code> and you should get an output similar to the following:</p>
803  <pre>
804(SHELL PROMPT)$ fcm make
805[init] make                # 2011-11-03 10:31:10Z
806[init] make config-parse   # 2011-11-03 10:31:10Z
807[info] config-file=/home/matt/tutorial/test/fcm-make.cfg
808[done] make config-parse   # 0.0s
809[init] make dest-init      # 2011-11-03 10:31:10Z
810[info] dest=frsn@eld081:/home/matt/tutorial/test
811[info] mode=new
812[done] make dest-init      # 0.0s
813[init] make extract        # 2011-11-03 10:31:10Z
814[info] location tutorial: 0: svn://fcm1/tutorial_svn/tutorial/branches/dev/matt/r1_133@811
815[info]   dest:    5 [A added]
816[info] source:    5 [U from base]
817[done] make extract        # 0.1s
818[init] make build          # 2011-11-03 10:31:10Z
819[info] sources: total=5, analysed=5, elapsed-time=0.0s, total-time=0.0s
820[info] compile   targets: modified=5, unchanged=0, total-time=0.3s
821[info] compile+  targets: modified=2, unchanged=0, total-time=0.0s
822[info] ext-iface targets: modified=1, unchanged=0, total-time=0.0s
823[info] link      targets: modified=1, unchanged=0, total-time=0.0s
824[info] TOTAL     targets: modified=9, unchanged=0, elapsed-time=0.4s
825[done] make build          # 0.4s
826[done] make                # 0.5s
827</pre>
828
829  <p>If nothing goes wrong, you should end up with the sub-direcories
830  <samp>extract/</samp> and <samp>build/</samp> in your working directory. The
831  <samp>extract/</samp> sub-directory contains the result of the extract and
832  the <samp>build/</samp> sub-directory contains the result of the build.</p>
833
834  <p>N.B. You should also find a <samp>.fcm-make/</samp> sub-directory. It is
835  used by <code>fcm make</code> as a working area for your extract and build.
836  It also contains a diagnostic <samp>log</samp> file generated by the latest
837  <code>fcm make</code> command. The log file contains the diagnostic output in
838  high verbosity. If anything goes wrong, it is worth checking the content of
839  the log file for clues.</p>
840
841  <p>The executable you have built is <samp>hello.exe</samp>, which is located
842  in the <samp>build/bin/</samp> sub-directory. You can test your executable by
843  running it. You should get an output similar to the following:</p>
844  <pre>
845(SHELL PROMPT)$ PATH=$PWD/build/bin:$PATH hello.exe
846hello: Hello Earthlings!
847hello_sub: Hello Earthlings!
848hello_huge_number: maximum integer: 2147483647
849hello_c: Hello World!
850</pre>
851
852  <h3 id="tutorial_merge">Merge changes from the trunk and resolve
853  conflicts</h3>
854
855  <p><em>Your branch is normally isolated from other development lines in your
856  project. However, at some point during your development, you may need to
857  merge your changes with those of your colleagues. In some cases, it is
858  desirable to merge changes regularly from the trunk to keep your branch up to
859  date with the latest development. The automatic merge provided by FCM allows
860  you to do this easily.</em></p>
861
862  <p><em>A merge results in a conflict if changes being applied to a file
863  overlap. FCM uses a graphical merge tool to help you resolve overlaps in file
864  text changes (</em>text conflicts<em>). If some of the changes include a
865  deletion, renaming, or addition of the file, a filesystem conflict (</em>tree
866  conflict<em>) may occur, which needs to be dealt with manually.</em></p>
867
868  <p>After completing this sub-section, you will learn how to:</p>
869
870  <ul>
871    <li>merge changes from the trunk into your working copy, and</li>
872
873    <li>resolve text and tree conflicts in your working copy.</li>
874  </ul>
875
876  <p>Further reading:</p>
877
878  <ul>
879    <li>Code Management System &gt; Basic Command Line Usage &gt; <a href=
880    "code_management.html#svn_basic_conflicts">Resolving Conflicts</a></li>
881
882    <li>Code Management System &gt; <a href=
883    "code_management.html#svn_branching">Branching &amp; Merging</a></li>
884
885    <li>Code Management Working Practices &gt; <a href=
886    "working_practices.html#branching">Branching &amp; Merging</a></li>
887
888    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm-conflicts">fcm
889    conflicts</a></li>
890
891    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm-merge">fcm
892    merge</a></li>
893  </ul>
894
895  <h4>Merge changes from the trunk into a working copy</h4>
896
897  <p>Perform the merge in your working copy.</p>
898
899  <p><dfn>Command line</dfn>: issue the <code>fcm merge</code> command.
900  E.g.</p>
901  <pre>
902(SHELL PROMPT)$ fcm merge trunk
903</pre>
904
905  <p>If there is more than one revision of the source that you can merge with,
906  you will be prompted for the revision number you wish to merge from. You will
907  not be prompted in this case, because there is only one revision of the
908  source that you can merge with.</p>
909
910  <p>Example:</p>
911  <pre>
912Eligible merge(s) from /tutorial/trunk: 2
913Merge: /tutorial/trunk@2
914 c.f.: /tutorial/trunk@1
915-------------------------------------------------------------------------dry-run
916--- Merging r2 into '.':
917U    src/subroutine/hello_c.c
918A    src/module/hello_number.f90
919C    src/module/hello_constants.f90
920   C src/module/hello_num.f90
921Summary of conflicts:
922  Text conflicts: 1
923  Tree conflicts: 1
924-------------------------------------------------------------------------dry-run
925Would you like to go ahead with the merge?
926Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
927Merge succeeded.
928</pre>
929
930  <h4>Status of the working copy after a merge</h4>
931
932  <p>In the output of the merge, the <samp>C</samp> status at the beginning of
933  a line indicates that the first file you changed,
934  <samp>src/module/hello_constants.f90</samp>, is now in <em>text
935  conflict</em>. The <samp>C</samp> status in the 4th column of a line
936  indicates that the second file you changed,
937  <samp>src/subroutines/hello_num.f90</samp>, is now in <em>tree conflict</em>.
938  If you run <code>fcm status</code>, you will see extra information about the
939  merge, which may help you to resolve the conflicts:</p>
940  <pre>
941=&gt; fcm status
942 M      .
943?       #commit_message#
944M       src/subroutine/hello_c.c
945?       src/module/hello_constants.f90.merge-left.r1
946?       src/module/hello_constants.f90.merge-right.r2
947?       src/module/hello_constants.f90.working
948      C src/module/hello_num.f90
949      &gt;   local edit, incoming delete upon merge
950A  +    src/module/hello_number.f90
951C       src/module/hello_constants.f90
952</pre>
953
954  <p>In the case of the file <samp>hello_constants.f90</samp>, the extra files
955  created (ending with <samp>working</samp>, <samp>merge-left.r1</samp>,
956  <samp>merge-right.r2</samp>) will be used to resolve the text conflict using
957  the 3-way difference tool <code>xxdiff</code>.</p>
958
959  <p>In the case of the file <samp>hello_num.f90</samp>, the extra line
960  underneath (<em>local edit, incoming delete upon merge</em>) displays the
961  conflict or dilemma that you must resolve - you have made a change to the
962  file in your branch (<em>local edit</em>) but someone has deleted the file on
963  the trunk (<em>incoming delete upon merge</em>). If you inspect the log of
964  the trunk, by typing e.g. <code>fcm log -v -rHEAD:1
965  fcm:tutorial/trunk</code>, you will find that someone has renamed
966  <samp>src/module/hello_num.f90</samp> to
967  <samp>src/module/hello_number.f90</samp>.</p>
968
969  <p>The line: <samp>M .</samp> just refers to Subversion's merge tracking,
970  which is not relevant here.</p>
971
972  <p>You will now have to resolve the conflicts.</p>
973
974  <h4>Resolve the conflicts</h4>
975
976  <p>Issue the <code>fcm conflicts</code> (or simply <code>fcm cf</code>)
977  command.</p>
978
979  <p>The <code>xxdiff</code> program comes into play:</p>
980
981  <p class="image"><img src="xxdiff_tutorial.png" alt="3-way diff" /></p>
982
983  <p>See the sub-section on <a href=
984  "code_management.html#svn_basic_conflicts">resolving conflicts</a>, or the
985  <cite>xxdiff User's Manual</cite> (click on <em>Help</em>) to guide you
986  through this process. (If you do not want to learn how to use
987  <code>xxdiff</code> now, you can just click on the highlighted line in the
988  left hand column, and select <kbd>Exit with MERGED</kbd> from the
989  <em>File</em> menu. This saves the file you are merging in as the result of
990  the merge, i.e. you have <em>merged</em> the changes).</p>
991
992  <p>On resolving this conflict, you will be asked to run <code>svn
993  resolved</code>. Answer <kbd>Yes</kbd>.</p>
994
995  <p>You are now prompted to try to solve the <em>tree conflict</em>.</p>
996  <pre>
997[info] src/module/hello_num.f90: in tree conflict.
998Locally: modified
999Externally: renamed to src/module/hello_number.f90
1000Answer (y) to keep the old name.
1001Answer (n) to accept the rename.
1002You can then merge in changes.
1003Keep the local version?
1004Enter "y" or "n" (or just press &lt;return&gt; for "n")
1005</pre>
1006
1007  <p>Entering <samp>y</samp> will keep the file as it is, and entering
1008  <samp>n</samp> will accept the external changes. Your problem is that the
1009  edit you made to <samp>hello_num.f90</samp> is no longer valid on the trunk,
1010  because there the file has been renamed to <samp>hello_number.f90</samp>. To
1011  Subversion, it looks like <samp>hello_num.f90</samp> disappeared. Your
1012  choices would be either to delete the new file by answering <samp>y</samp>,
1013  or incorporate your changes into the new file (<samp>hello_number.f90</samp>)
1014  by answering <samp>n</samp>. As the new filename comes from the trunk, we
1015  would normally accept it and incorporate changes into it, rather than delete
1016  it.</p>
1017
1018  <p>Answer <samp>n</samp> to accept the renaming of the file and merge in
1019  changes. This will occur using <code>xxdiff</code>, as above.</p>
1020
1021  <p>Exit the <code>xxdiff</code> window as before, with <kbd>Exit with
1022  MERGED</kbd>.</p>
1023
1024  <p>If you now run <code>status</code>, you will notice that these extra
1025  conflict files have disappeared, and there are no more <samp>C</samp>
1026  filename statuses.</p>
1027
1028  <p>Example:</p>
1029  <pre>
1030=&gt; fcm status
1031 M      .
1032?       #commit_message#
1033M       src/subroutine/hello_c.c
1034D       src/module/hello_num.f90
1035A  +    src/module/hello_number.f90
1036</pre>
1037
1038  <p>You have now resolved all the conflicts.</p>
1039
1040  <h4>Commit after the merge</h4>
1041
1042  <p>It is important to remember that the <code>fcm merge</code> command only
1043  applies changes to your working copy. Therefore, you must now commit the
1044  change in order for it to become permanent in the repository. Similar to
1045  other changes, it is a good practice to use <code>fcm diff</code> to inspect
1046  the changes before committing.</p>
1047
1048  <p>When you run <code>fcm commit</code>, you will be prompted to edit the
1049  commit log as usual. However, you may notice that a standard template is
1050  already provided for you by the <code>fcm merge</code> command. In most
1051  cases, the standard message should be sufficient. However, if you want to add
1052  extra comment to the commit, please do so <strong>above</strong> the line
1053  that says <samp>--Add your commit message ABOVE - do not alter this line or
1054  those below--</samp>. This is useful, for example, if there were significant
1055  issues addressed in the merge.</p>
1056
1057  <h3 id="tutorial_review-ticket">Review changes</h3>
1058
1059  <p><em>For the purpose of this tutorial, we assume that your changes are
1060  complete, have been tested and committed to the repository, and are now ready
1061  for review. You should assign the ticket to the reviewer and inform him/her
1062  where to find the changes you wish him/her to review. The reviewer will
1063  record any issues in the ticket, perhaps linking to other documents as
1064  required. Once completed, he/she will record the outcome in the ticket and
1065  assign it back to the you.</em></p>
1066
1067  <p>After completing this sub-section, you will learn how to:</p>
1068
1069  <ul>
1070    <li>display changes in a branch, and</li>
1071
1072    <li>re-assign a ticket.</li>
1073  </ul>
1074
1075  <p>Further reading:</p>
1076
1077  <ul>
1078    <li>Code Management System &gt; Branching &amp; Merging &gt; <a href=
1079    "code_management.html#svn_branching_info">Getting Information About
1080    Branches</a></li>
1081
1082    <li>Code Management System &gt; <a href="code_management.html#trac">Using
1083    Trac</a></li>
1084
1085    <li>Code Management Working Practices &gt; <a href=
1086    "working_practices.html#tickets">Using Tickets</a></li>
1087
1088    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm-diff">fcm
1089    diff</a></li>
1090  </ul>
1091
1092  <h4>Display changes in a branch</h4>
1093
1094  <p>Before you ask someone to review your code, it is often a good idea to
1095  have a look at the changes one more time. To view the changes in a branch,
1096  you can look at all the changes relative to its base.</p>
1097
1098  <p><dfn>Command line</dfn>: issue the <code>fcm branch-diff
1099  --graphical</code> (or simply <code>fcm bdi -g</code>) command.</p>
1100
1101  <p>You should be presented with the differences between the branch and the
1102  trunk (since the last merge).</p>
1103
1104  <p>Note: you can also use the <code>--trac</code> (<code>-t</code>) option
1105  instead of <code>--graphical</code> (<code>-g</code>) to view the changes in
1106  a branch using Trac rather than using a graphical diff tool.</p>
1107
1108  <p><dfn>Command line</dfn>: issue the <code>fcm branch-diff --trac</code> (or
1109  simply <code>fcm bdi -t</code>) command.</p>
1110
1111  <p>Take note of the Trac URL for displaying the differences. The part that
1112  begins with <code>diff:</code> is of particular interest to you, as it is a
1113  Trac link that can be inserted into a Trac wiki/ticket. In the above example,
1114  the Trac link would look like:
1115  <samp>diff:/tutorial/trunk@2///tutorial/branches/dev/matt/r1_133@813</samp>.</p>
1116
1117  <h4>Re-assign a ticket to a reviewer</h4>
1118
1119  <p>Back in your ticket, add an appropriate comment showing where to find your
1120  changes, in the <em>Add/Change</em> box. Include a link to your branch and a
1121  diff link (see above) in the comment. For example:</p>
1122  <pre>
1123The [log:tutorial/branches/dev/matt/r1_133@811:813] branch proposes
1124changes to the greeting in hello_constants.f90. It also contains some new
1125documents. See
1126[diff:/tutorial/trunk@2///tutorial/branches/dev/matt/r1_133@813] for the
1127changes.
1128
1129Fred, could you review the change, please?
1130</pre>
1131
1132  <p>Note: the syntax
1133  <samp>[log:tutorial/branches/dev/matt/r1_133@811:813]</samp> will be
1134  translated by Trac into a link to the revision log browser to display the log
1135  between revision 811 and 813 of the <samp>branches/dev/matt/r1_133</samp>
1136  branch in the <samp>tutorial</samp> project; and the syntax
1137  <samp>[diff:/tutorial/trunk@2///tutorial/branches/dev/matt/r1_133@813]</samp>
1138  will be translated into a link to display the differences between the trunk
1139  at revision 2 and the branch at revision 813. Click on <kbd>Preview</kbd> and
1140  check that the links work correctly.</p>
1141
1142  <p>To re-assign a ticket to your reviewer, click on the <kbd>reassign
1143  to</kbd> button in the <em>Action</em> box section and enter the reviewer's
1144  User ID.</p>
1145
1146  <p>When you are ready, click on <kbd>Submit changes</kbd>.</p>
1147
1148  <h4>Reassign the ticket back to the author</h4>
1149
1150  <p>For the purpose of this tutorial, you will act as the reviewer of the
1151  changes you have made. Following the review, you should record its outcome
1152  and re-assign the ticket back to the author. Enter the comment <kbd>No issues
1153  were found during the review</kbd>. Click on the <kbd>reassign to</kbd>
1154  button in the <em>Action</em> box section, and enter your guest account name.
1155  Click on <kbd>Submit changes</kbd> when you are ready.</p>
1156
1157  <h3 id="tutorial_merge-back">Commit to the trunk</h3>
1158
1159  <p><em>Your changes in the branch have been tested and reviewed. It is now
1160  time to merge and commit it to the trunk. Once you have committed your
1161  change, you will close your ticket to complete the work cycle.</em></p>
1162
1163  <p>After completing this sub-section, you will learn how to:</p>
1164
1165  <ul>
1166    <li>switch a working copy,</li>
1167
1168    <li>merge and commit your changes into the trunk, and</li>
1169
1170    <li>close a ticket</li>
1171  </ul>
1172
1173  <p>Further reading:</p>
1174
1175  <ul>
1176    <li>Code Management System &gt; <a href=
1177    "code_management.html#svn_branching">Branching &amp; Merging</a></li>
1178
1179    <li>Code Management Working Practices &gt; <a href=
1180    "working_practices.html#branching">Branching &amp; Merging</a></li>
1181
1182    <li>FCM Command Reference &gt; <a href="command_ref.html#fcm-switch">fcm
1183    switch</a></li>
1184  </ul>
1185
1186  <h4>Switch a working copy to point to the trunk</h4>
1187
1188  <p><dfn>Command line</dfn>: issue the <code>fcm switch</code> (or simply
1189  <code>fcm sw</code>) command. E.g.:</p>
1190  <pre>
1191(SHELL PROMPT)$ fcm sw trunk
1192</pre>
1193
1194  <p><dfn>Command line</dfn>: To check that your working copy is pointing to
1195  the trunk, issue the <code>fcm info</code> command.</p>
1196
1197  <h4>Merge and commit your changes into the trunk</h4>
1198
1199  <p><dfn>Command line</dfn>: issue the <code>fcm merge</code> command.
1200  E.g.</p>
1201  <pre>
1202(SHELL PROMPT)$ fcm merge branches/dev/matt/r1_133
1203</pre>
1204
1205  <p>Example:</p>
1206  <pre>
1207Eligible merge(s) from /tutorial/branches/dev/matt/r1_133: 813 812
1208Enter a revision (or just press &lt;return&gt; for "813"):
1209Merge: /tutorial/branches/dev/matt/r1_133@813
1210 c.f.: /tutorial/trunk@2
1211-------------------------------------------------------------------------dry-run
1212--- Merging differences between repository URLs into '.':
1213A    doc/new_file.txt
1214A    doc/add.html
1215D    doc/hello.html
1216U    src/module/hello_number.f90
1217U    src/module/hello_constants.f90
1218-------------------------------------------------------------------------dry-run
1219Would you like to go ahead with the merge?
1220Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
1221Merge succeeded.
1222</pre>
1223
1224  <p>Since there is more than one revision available for merging, you will be
1225  prompted for the revision number you wish to merge from. The default is the
1226  last changed revision of your branch. which is the revision you want to merge
1227  with, so you should just proceed with the default.</p>
1228
1229  <p>Since we merged in the latest changes from the trunk into the branch,
1230  there should be no conflicts from this merge.</p>
1231
1232  <p>Once again, please remember that the merge command only changes your
1233  working copy. You need to commit the change before it becomes permanent in
1234  the repository. Before you commit to the trunk, however, it is often sensible
1235  to have a last look at what you are going to change using the
1236  <code>diff</code> command.</p>
1237
1238  <p>Note: We have set up the repository to prevent any commits to the trunk to
1239  preserve the tutorial for other users, so your commit to the trunk will fail.
1240  However, you should try doing it any way to complete the exercise.</p>
1241
1242  <p><dfn>Command line</dfn>: issue the <code>fcm commit</code> (or simply
1243  <code>fcm ci</code>) command.</p>
1244
1245  <p>A text editor will appear to allow you to edit the commit message. You
1246  must add a commit message to describe your change <strong>above</strong> the
1247  line that says <samp>--Add your commit message ABOVE - do not alter this line
1248  or those below--</samp>. Since you are going to commit changes to the trunk,
1249  you should provide a useful message, including a link to your ticket. For
1250  example:</p>
1251  <pre>
1252#133: tutorial completed.
1253</pre>
1254
1255  <p>When you are ready, save your change and exit the editor.</p>
1256
1257  <p>As we have said before, the command will fail when you try to proceed with
1258  the commit.</p>
1259
1260  <h4>Close your ticket</h4>
1261
1262  <p>As you have completed your work, you should now update and close your
1263  ticket. In real life, you will typically include a closing comment with an
1264  appropriate Trac wiki link to the changeset in the trunk that fixes the
1265  ticket.</p>
1266
1267  <p>Since you cannot commit to the trunk in the tutorial, you can include a
1268  Trac link to the latest changeset in your branch. For example, you can put
1269  <samp>r813: fixed.</samp> in the comment. To mark the ticket as
1270  <em>fixed</em>, move down to the <em>Action</em> box section, click on
1271  <kbd>resolve as</kbd> and choose <kbd>fixed</kbd>. Use <kbd>Preview</kbd> to
1272  ensure that your links work correctly. When you are happy, click on
1273  <kbd>Submit changes</kbd>.</p>
1274
1275  <h3 id="tutorial_extra-extract">Extra activities on the extract and build
1276  systems</h3>
1277
1278  <p><em>The extract and build systems are very flexible. If you have time, you
1279  may want to explore their uses in more depth.</em></p>
1280
1281  <p>After completing this sub-section, you will learn how to:</p>
1282
1283  <ul>
1284    <li>extract from a working copy,</li>
1285
1286    <li>change a compiler flag, and</li>
1287
1288    <li>extract from a particular branch and/or revision from the
1289    repository.</li>
1290  </ul>
1291
1292  <p>Further reading:</p>
1293
1294  <ul>
1295    <li><a href="make.html">FCM Make</a></li>
1296  </ul>
1297
1298  <h4>Extract from a working copy</h4>
1299
1300  <p>Modify the source files in your working copy and commit the changes back
1301  to your branch in the repository. Re-run <code><a href=
1302  "command_ref.html#fcm-make">fcm make</a></code> and see the results of the
1303  changes.</p>
1304
1305  <p>In fact, you can test changes in your working copy directly using a
1306  similar extract and build mechanism. In such case, you need to modify the
1307  <code><a href=
1308  "annex_cfg.html#make.extract.location">extract.location</a></code>
1309  declaration. For example:</p>
1310  <pre>
1311extract.location[tutorial] = $HOME/work/tutorial
1312</pre>
1313
1314  <h4>Change a compiler flag</h4>
1315
1316  <p>Modify the compiler flags, and re-run <code><a href=
1317  "command_ref.html#fcm-make">fcm make</a></code> and see the results of the
1318  changes. To modify the compiler flags, edit your FCM make configuration file,
1319  and add the declarations for changing compiler flags. For example:</p>
1320  <pre>
1321# Declare extra options for Fortran compiler
1322build.prop{fc.flags} = -i8 -O3
1323</pre>
1324
1325  <p>For further information on how to set your compiler flags, please refer to
1326  the <a href="make.html">FCM Make</a> &gt; <a href=
1327  "make.html#build">Build</a>.</p>
1328
1329  <h4>Extract from a particular branch and/or revision</h4>
1330
1331  <p>Try extracting from an earlier revision of your branch. Suppose the HEAD
1332  of your branch is revision 813, and the branch was created at an earlier
1333  revision. You can extract your branch at, say, revision 811 by adding the
1334  following to the <code><a href=
1335  "annex_cfg.html#make.extract.location">extract.location</a></code>
1336  declaration in your FCM make configuration file:</p>
1337  <pre>
1338extract.location[tutorial] = branches/dev/$LOGNAME/r1_133@811
1339</pre>
1340
1341  <p>You can also try extracting from the trunk. To extract from the
1342  <samp>trunk@HEAD</samp>, simply comment out or remove the <code><a href=
1343  "annex_cfg.html#make.extract.location">extract.location</a></code>
1344  declaration. To extract from a given revision of the trunk, you will need to
1345  modify the <code><a href=
1346  "annex_cfg.html#make.extract.location">extract.location</a></code>
1347  declaration in your FCM make configuration file. For example:</p>
1348  <pre>
1349extract.location[tutorial] = trunk@1
1350</pre>
1351
1352  <h3 id="tutorial_delete-branch">Delete your branch</h3>
1353
1354  <p><em>You should remove your branch when it is no longer required. When you
1355  remove it, it becomes invisible from the HEAD revision, but will continue to
1356  exist in the repository, should you want to refer to it in the
1357  future.</em></p>
1358
1359  <p>After completing this sub-section, you will learn how to:</p>
1360
1361  <ul>
1362    <li>list branches owned by you, and</li>
1363
1364    <li>delete a branch.</li>
1365  </ul>
1366
1367  <p>Further reading:</p>
1368
1369  <ul>
1370    <li>Code Management System &gt; Branching &amp; Merging &gt; <a href=
1371    "code_management.html#svn_branching_list">Listing Branches Created by You
1372    or Other Users</a></li>
1373
1374    <li>Code Management System &gt; Branching &amp; Merging &gt; <a href=
1375    "code_management.html#svn_branching_delete">Deleting Branches</a></li>
1376  </ul>
1377
1378  <h4>List branches owned by you</h4>
1379
1380  <p>If you forget what your branch is called and/or what other branches you
1381  have created, you can get a listing of all the branches you have created in a
1382  project.</p>
1383
1384  <p><dfn>Command line</dfn>: issue the <code>fcm branch-list</code> (or simply
1385  <code>fcm bls</code>) command</p>
1386
1387  <h4>Delete a branch</h4>
1388
1389  <p>Switch your working copy to point back to your branch. Before you do so,
1390  revert any changes you have made in the working copy by issuing the <code>fcm
1391  revert -R .</code> command. If a <samp>#commit_message#</samp> file exists,
1392  remove it by issuing the <code>rm '#commit_message#'</code> command.</p>
1393
1394  <p><dfn>Command line</dfn>: issue the <code>fcm switch &lt;URL&gt;</code> (or
1395  simply <code>fcm sw &lt;URL&gt;</code>) command.</p>
1396
1397  <p>You can continue your work in the branch if you wish, but once you have
1398  finished all the work, you should delete it.</p>
1399
1400  <p><dfn>Command line</dfn>: issue the <code>fcm branch-delete</code> (or
1401  simply <code>fcm bdel</code>) command.</p>
1402
1403  <p>Example:</p>
1404  <pre>
1405URL: svn://fcm1/tutorial_svn/tutorial/branches/dev/matt/r1_133
1406Repository Root: svn://fcm1/tutorial_svn
1407Repository UUID: cb858ce8-0f05-0410-9e64-efa98b760b62
1408Revision: 813
1409Node Kind: directory
1410Last Changed Author:
1411Last Changed Rev: 813
1412Last Changed Date: 2005-11-09 09:11:57 +0000 (Wed, 09 Nov 2005)
1413--------------------------------------------------------------------------------
1414Branch Create Rev: 811
1415Branch Create Date: 2005-11-09 08:34:22 +0000 (Wed, 09 Nov 2005)
1416Branch Parent: svn://fcm1/tutorial_svn/tutorial/trunk@1
1417--------------------------------------------------------------------------------
1418Last Merge From Trunk: /tutorial/branches/dev/matt/r1_133@813 /tutorial/trunk@2
1419Avail Merges Into Trunk: 813 812
1420[info] gvim -f: starting commit message editor...
1421Change summary:
1422------------------------------------------------------------------------
1423D    svn://fcm1/tutorial_svn/tutorial/branches/dev/matt/r1_133
1424------------------------------------------------------------------------
1425Commit message is as follows:
1426------------------------------------------------------------------------
1427Deleted tutorial/branches/dev/matt/r1_133.
1428------------------------------------------------------------------------
1429Would you like to go ahead and delete this branch?
1430Enter "y" or "n" (or just press &lt;return&gt; for "n"): y
1431Deleting branch svn://fcm1/tutorial_svn/tutorial/branches/dev/matt/r1_133 ...
1432
1433Committed revision 813.
1434</pre>
1435
1436  <p>You will be prompted to edit the commit message file. A standard template
1437  is automatically supplied for the commit. However, if you want to add extra
1438  comment for the branch, please do so <strong>above</strong> the line that
1439  says <samp>--Add your commit message ABOVE - do not alter this line or those
1440  below--</samp>. Save your change and exit the editor.</p>
1441
1442  <p>Your working copy is now pointing to a branch that no longer exists at the
1443  HEAD revision of the repository. If you want to try the tutorial again, you
1444  may want to create another branch, and switch your working copy to point to
1445  the new branch. Otherwise, you can remove your working copy by issuing a
1446  careful <code>rm -rf</code> command.</p>
1447
1448  <h3 id="tutorial_delete-final-comments">Final comments</h3>
1449
1450  <p>We have guided you through the basics of the complete change process,
1451  using recommended ways of working. Most of the basic and important commands
1452  have been covered by the tutorial. (The exceptions are <code>fcm log</code>
1453  and <code>fcm update</code>, which you may have to use regularly. For
1454  information on these commands, please refer to the section on <a href=
1455  "http://svnbook.red-bean.com/en/1.8/svn.tour.history.html#svn.tour.history.log">
1456  svn log</a> and <a href=
1457  "http://svnbook.red-bean.com/en/1.8/svn.tour.cycle.html#svn.tour.cycle.update">
1458  Update Your Working Copy</a> in the <a href=
1459  "http://svnbook.red-bean.com/en/1.8/">Subversion book</a>.) You should now be
1460  in a position to continue with your development work with FCM. However, if at
1461  any time you are unsure about any aspect of using FCM, please consult the
1462  relevant section of the <a href="index.html">FCM User Guide</a>.</p>
1463
1464  <p>Feel free to use the tutorial, at any time, for testing out any aspect of
1465  the system. You may wish to do this rather than use your own repository and
1466  ticket system, to avoid cluttering them with unwanted junk.</p>
1467
1468  </div>
1469  </div>
1470  </div>
1471
1472  <hr/>
1473  <div class="container-fluid text-center">
1474    <div class="row"><div class="col-md-12">
1475    <address><small>
1476      &copy; British Crown Copyright 2006-16
1477      <a href="http://www.metoffice.gov.uk">Met Office</a>.
1478      See <a href="../etc/fcm-terms-of-use.html">Terms of Use</a>.<br />
1479      This document is released under the British <a href=
1480      "http://www.nationalarchives.gov.uk/doc/open-government-licence/" rel=
1481      "license">Open Government Licence</a>.<br />
1482    </small></address>
1483    </div></div>
1484  </div>
1485
1486  <script type="text/javascript" src="../etc/jquery.min.js"></script>
1487  <script type="text/javascript" src="../etc/bootstrap/js/bootstrap.min.js"></script>
1488  <script type="text/javascript" src="../etc/fcm.js"></script>
1489  <script type="text/javascript" src="../etc/fcm-version.js"></script>
1490</body>
1491</html>
Note: See TracBrowser for help on using the repository browser.