source: LMDZ6/trunk/tools/fcm/doc/user_guide/getting_started.html @ 4601

Last change on this file since 4601 was 1578, checked in by jghattas, 13 years ago
  • Add fcm in LMDZ5/tools directory

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