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