[1578] | 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 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 <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 | <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"><View Tickets></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"><Search></span> utility at the top right hand corner of each |
---|
| 315 | Trac page. (If you enter <tt>#<number></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"><accept |
---|
| 330 | ticket></span> in the <em>Action</em> box at the bottom of the page, and |
---|
| 331 | then click on <span class="mono"><Submit changes></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 > <a href= |
---|
| 353 | "code_management.html#svn_gui">Using the GUI</a></li> |
---|
| 354 | |
---|
| 355 | <li>FCM Command Reference > <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> > |
---|
| 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 > Branching & Merging > <a href= |
---|
| 391 | "code_management.html#svn_branching_create">Creating Branches</a></li> |
---|
| 392 | |
---|
| 393 | <li>Code Management Working Practices > <a href= |
---|
| 394 | "working_practices.html#branching">Branching & Merging</a></li> |
---|
| 395 | |
---|
| 396 | <li>FCM Command Reference > <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"><Branch></span> on the |
---|
| 409 | top menu bar of the GUI. Check the <span class="mono"><create></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"><test::user></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"><trunk></span> and |
---|
| 428 | the prefix option as <span class="mono"><normal></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"><Run></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"><Yes></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> |
---|
| 479 | Created 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>[<number>]</tt> into a link to |
---|
| 493 | the numbered changeset.</li> |
---|
| 494 | </ul> |
---|
| 495 | |
---|
| 496 | <p>Click on <Preview> and check that the links work correctly, and on |
---|
| 497 | <span class="mono"><Submit changes></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 > <a href= |
---|
| 517 | "code_management.html#svn_concepts">Basic Concepts</a></li> |
---|
| 518 | |
---|
| 519 | <li>FCM Command Reference > <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"><Checkout></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"><Run></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 | => svn co --revision HEAD svn://fcm1/tutorial_svn/tutorial/branches/test/frsn/r1_tutorial |
---|
| 567 | A r1_tutorial/cfg |
---|
| 568 | A r1_tutorial/cfg/ext.cfg |
---|
| 569 | A r1_tutorial/doc |
---|
| 570 | A r1_tutorial/doc/hello.html |
---|
| 571 | A r1_tutorial/src |
---|
| 572 | A r1_tutorial/src/subroutine |
---|
| 573 | A r1_tutorial/src/subroutine/hello_c.c |
---|
| 574 | A r1_tutorial/src/subroutine/hello_sub.f90 |
---|
| 575 | A r1_tutorial/src/module |
---|
| 576 | A r1_tutorial/src/module/hello_constants.f90 |
---|
| 577 | A r1_tutorial/src/program |
---|
| 578 | A r1_tutorial/src/program/hello.f90 |
---|
| 579 | Checked 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 > <a href= |
---|
| 609 | "code_management.html#svn_basic">Basic Command Line Usage</a></li> |
---|
| 610 | |
---|
| 611 | <li>FCM Command Reference > <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"><Status></span> and then on <span |
---|
| 643 | class="mono"><Run></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' >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"><Status></span> and |
---|
| 688 | then on <span class="mono"><Run></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 | => svn status |
---|
| 699 | D doc/hello.html |
---|
| 700 | A doc/new_file.txt |
---|
| 701 | A + doc/add.html |
---|
| 702 | M 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"><Diff></span> and then |
---|
| 721 | on <span class= "mono"><Run></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 > <a href= |
---|
| 745 | "code_management.html#svn_basic">Basic Command Line Usage</a></li> |
---|
| 746 | |
---|
| 747 | <li>FCM Command Reference > <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"><Commit></span> and |
---|
| 757 | then on <span class="mono"><Run></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"><Yes></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> |
---|
| 777 | Starting nedit to create commit message ... |
---|
| 778 | Commit 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: <top>] |
---|
| 787 | |
---|
| 788 | D doc/hello.html |
---|
| 789 | A doc/new_file.txt |
---|
| 790 | A + doc/add.html |
---|
| 791 | M src/module/hello_constants.f90 |
---|
| 792 | ------------------------------------------------------------------------ |
---|
| 793 | Adding doc/add.html |
---|
| 794 | Deleting doc/hello.html |
---|
| 795 | Adding doc/new_file.txt |
---|
| 796 | Sending src/module/hello_constants.f90 |
---|
| 797 | Transmitting file data .. |
---|
| 798 | Committed revision 6. |
---|
| 799 | Performing update to make sure your working copy is at this new revision ... |
---|
| 800 | At 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"><Timeline></span> in Trac. Drill down to |
---|
| 809 | your changeset and see how it appears. (Alternatively, if you enter |
---|
| 810 | "<tt>[<number>]</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 |
---|
| 885 | cfg::type ext |
---|
| 886 | cfg::version 1.0 |
---|
| 887 | |
---|
| 888 | # Extract destination root directory |
---|
| 889 | dest::rootdir $HOME/tutorial/build |
---|
| 890 | |
---|
| 891 | # Location of the source in the "r1_tutorial" branch |
---|
| 892 | repos::tutorial::base fcm:tutorial_br/test/$LOGNAME/r1_tutorial |
---|
| 893 | |
---|
| 894 | # Extract all sub-directories under the above URL |
---|
| 895 | expsrc::tutorial::base src |
---|
| 896 | |
---|
| 897 | # Fortran compiler, C compiler and linker commands respectively |
---|
| 898 | # You may need to redefine these for different platforms |
---|
| 899 | bld::tool::fc ifc |
---|
| 900 | bld::tool::cc gcc |
---|
| 901 | bld::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 |
---|
| 935 | Extraction started on Thu Oct 27 13:54:06 2005. |
---|
| 936 | Config file (ext): /net/home/h01/frsn/tutorial/build/ext.cfg |
---|
| 937 | ->Extract: start |
---|
| 938 | Number of directories created : 4 |
---|
| 939 | Number of updated files : 4 |
---|
| 940 | ->Extract: 1 second |
---|
| 941 | ->TOTAL : 1 second |
---|
| 942 | Extraction 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>err |
---|
| 965 | Build command started on Fri Oct 14 09:15:38 2005. |
---|
| 966 | ->gt;Setup : start |
---|
| 967 | Config file (bld): /net/home/h01/frsn/tutorial/build/cfg/bld.cfg |
---|
| 968 | ->Setup : 0 second |
---|
| 969 | ->Pre-process : start |
---|
| 970 | ->Pre-process : 0 second |
---|
| 971 | ->Scan dependency : start |
---|
| 972 | Scanned files in 3 package(s) for dependency |
---|
| 973 | Updated make rules for 3 package(s). |
---|
| 974 | Updated Makefile: /net/home/h01/frsn/tutorial/build/bld/Makefile |
---|
| 975 | ->Scan dependency : 1 second |
---|
| 976 | ->Generate interface : start |
---|
| 977 | Number of generated interfaces: 1 |
---|
| 978 | ->Generate interface : 0 second |
---|
| 979 | ->Make : start |
---|
| 980 | ifc -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 |
---|
| 982 | ifc -o hello.o -I/home/h01/frsn/tutorial/build/inc -c |
---|
| 983 | /home/h01/frsn/tutorial/build/src/tutorial/src/program/hello.f90 |
---|
| 984 | ifc -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 |
---|
| 986 | gcc -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 |
---|
| 988 | ifc -o hello.exe /home/h01/frsn/tutorial/build/obj/hello.o |
---|
| 989 | -L/home/h01/frsn/tutorial/build/lib -l__fcm__hello |
---|
| 990 | ->Make : 3 seconds |
---|
| 991 | ->TOTAL : 4 second |
---|
| 992 | Build 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 |
---|
| 1012 | Hello: Hello Earthlings! |
---|
| 1013 | Hello_Sub: Hello Earthlings! |
---|
| 1014 | Hello_Sub: maximum integer: 2147483647 |
---|
| 1015 | Hello_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 > Basic Command Line Usage > <a href= |
---|
| 1047 | "code_management.html#svn_basic_conflicts">Resolving Conflicts</a></li> |
---|
| 1048 | |
---|
| 1049 | <li>Code Management System > <a href= |
---|
| 1050 | "code_management.html#svn_branching">Branching & Merging</a></li> |
---|
| 1051 | |
---|
| 1052 | <li>Code Management Working Practices > <a href= |
---|
| 1053 | "working_practices.html#branching">Branching & Merging</a></li> |
---|
| 1054 | |
---|
| 1055 | <li>FCM Command Reference > <a href="command_ref.html#fcm_svn_cf">fcm |
---|
| 1056 | conflicts</a></li> |
---|
| 1057 | |
---|
| 1058 | <li>FCM Command Reference > <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"><Merge></span>. Enter |
---|
| 1072 | "<tt>trunk</tt>" into the Source entry box and click on <span class= |
---|
| 1073 | "mono"><Run></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"><Yes></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> |
---|
| 1092 | Available Merges From /tutorial/trunk: 2 |
---|
| 1093 | About to merge in changes from tutorial/trunk@2 compared with tutorial/trunk@1 |
---|
| 1094 | This merge will result in the following changes: |
---|
| 1095 | ------------------------------------------------------------------------ |
---|
| 1096 | U src/subroutine/hello_c.c |
---|
| 1097 | C src/module/hello_constants.f90 |
---|
| 1098 | ------------------------------------------------------------------------ |
---|
| 1099 | Performing merge ... |
---|
| 1100 | U src/subroutine/hello_c.c |
---|
| 1101 | C 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 | => svn status |
---|
| 1123 | M 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 |
---|
| 1127 | C 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"><Conflicts></span> and |
---|
| 1139 | then on <span class="mono"><Run></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"><Help></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"><Yes></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> |
---|
| 1170 | Conflicts in file: src/module/hello_constants.f90 |
---|
| 1171 | All merge conflicts resolved |
---|
| 1172 | Resolved conflicted state of 'hello_constants.f90' |
---|
| 1173 | => svn status |
---|
| 1174 | M src/subroutine/hello_c.c |
---|
| 1175 | M 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 > Branching & Merging > <a href= |
---|
| 1218 | "code_management.html#svn_branching_info">Getting Information About |
---|
| 1219 | Branches</a></li> |
---|
| 1220 | |
---|
| 1221 | <li>Code Management System > <a href="code_management.html#trac">Using |
---|
| 1222 | Trac</a></li> |
---|
| 1223 | |
---|
| 1224 | <li>Code Management Working Practices > <a href= |
---|
| 1225 | "working_practices.html#tickets">Using Tickets</a></li> |
---|
| 1226 | |
---|
| 1227 | <li>FCM Command Reference > <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"><Diff></span>. Check the |
---|
| 1241 | box <span class="mono"><Show differences relative to the base of the |
---|
| 1242 | branch></span>, and click on <span class="mono"><Run></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> |
---|
| 1265 | The [log:tutorial/branches/test/frsn/r1_tutorial@5:7] branch proposes changes to |
---|
| 1266 | the 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 |
---|
| 1268 | changes. |
---|
| 1269 | |
---|
| 1270 | Fred, 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 <Preview> 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"><reassign to></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"><Submit |
---|
| 1291 | changes></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"><reassign |
---|
| 1299 | to></span> button in the <em>Action</em> box section, and enter your guest |
---|
| 1300 | account name. Click on <span class="mono"><Submit changes></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 > <a href= |
---|
| 1324 | "code_management.html#svn_branching">Branching & Merging</a></li> |
---|
| 1325 | |
---|
| 1326 | <li>Code Management Working Practices > <a href= |
---|
| 1327 | "working_practices.html#branching">Branching & Merging</a></li> |
---|
| 1328 | |
---|
| 1329 | <li>FCM Command Reference > <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"><Switch></span>. Enter |
---|
| 1342 | "<tt>trunk</tt>" as the URL and then click on <span class= |
---|
| 1343 | "mono"><Run></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"><Merge></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"><Run></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> |
---|
| 1370 | Available Merges From /tutorial/branches/test/frsn/r1_tutorial: 7 6 |
---|
| 1371 | About to merge in changes from /tutorial/branches/test/frsn/r1_tutorial@7 |
---|
| 1372 | compared with /tutorial/trunk@2 |
---|
| 1373 | This merge will result in the following changes: |
---|
| 1374 | ------------------------------------------------------------------------ |
---|
| 1375 | D doc/hello.html |
---|
| 1376 | A doc/new_file.txt |
---|
| 1377 | U src/module/hello_constants.f90 |
---|
| 1378 | A add.html |
---|
| 1379 | ------------------------------------------------------------------------ |
---|
| 1380 | Performing merge ... |
---|
| 1381 | D doc/hello.html |
---|
| 1382 | A doc/new_file.txt |
---|
| 1383 | U src/module/hello_constants.f90 |
---|
| 1384 | A 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"><Yes></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"><Commit></span> and |
---|
| 1415 | then on <span class="mono"><Run></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> |
---|
| 1428 | For #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"><resolve as></span> and choose <em>fixed</em>. Use <span class= |
---|
| 1453 | "mono"><Preview></span> to ensure that your links work correctly. When |
---|
| 1454 | you are happy, click on <span class="mono"><Submit changes></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> |
---|
| 1493 | repos::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 |
---|
| 1504 | bld::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> |
---|
| 1518 | version::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> |
---|
| 1525 | repos::tutorial::base fcm:tutorial_tr/src |
---|
| 1526 | |
---|
| 1527 | # Extract with and without the following line and note the difference! |
---|
| 1528 | version::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 > Branching & Merging > <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 > Branching & Merging > <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"><Branch></span>, and |
---|
| 1567 | then on the <span class= "mono"><list></span> radio button. Click on |
---|
| 1568 | <span class= "mono"><Run></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 <URL></tt> (or simply |
---|
| 1575 | <tt>fcm sw <URL></tt>) command.</p> |
---|
| 1576 | |
---|
| 1577 | <p><em>FCM GUI</em>: click on <span class="mono"><Switch></span>. Enter |
---|
| 1578 | the name of your branch as the URL and click on <span |
---|
| 1579 | class="mono"><Run></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"><Branch></span> in the GUI. Check |
---|
| 1585 | the <span class= "mono"><delete></span> radio button, and click <span |
---|
| 1586 | class= "mono"><Run></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> |
---|
| 1596 | URL: svn://fcm1/tutorial_svn/tutorial/branches/test/frsn/r1_tutorial |
---|
| 1597 | Repository Root: svn://fcm1/tutorial_svn |
---|
| 1598 | Repository UUID: cb858ce8-0f05-0410-9e64-efa98b760b62 |
---|
| 1599 | Revision: 7 |
---|
| 1600 | Node Kind: directory |
---|
| 1601 | Last Changed Author: |
---|
| 1602 | Last Changed Rev: 7 |
---|
| 1603 | Last Changed Date: 2005-11-09 09:11:57 +0000 (Wed, 09 Nov 2005) |
---|
| 1604 | -------------------------------------------------------------------------------- |
---|
| 1605 | Branch Create Rev: 5 |
---|
| 1606 | Branch Create Date: 2005-11-09 08:34:22 +0000 (Wed, 09 Nov 2005) |
---|
| 1607 | Branch Parent: svn://fcm1/tutorial_svn/tutorial/trunk@1 |
---|
| 1608 | -------------------------------------------------------------------------------- |
---|
| 1609 | Last Merge From Trunk: /tutorial/branches/test/frsn/r1_tutorial@7 |
---|
| 1610 | /tutorial/trunk@2 |
---|
| 1611 | Avail Merges Into Trunk: 7 6 |
---|
| 1612 | Starting nedit to create commit message ... |
---|
| 1613 | Commit message is as follows: |
---|
| 1614 | ------------------------------------------------------------------------ |
---|
| 1615 | Deleted tutorial/branches/test/frsn/r1_tutorial. |
---|
| 1616 | --This line, and those below, will be ignored-- |
---|
| 1617 | D svn://fcm1/tutorial_svn/tutorial/branches/test/frsn/r1_tutorial |
---|
| 1618 | ------------------------------------------------------------------------ |
---|
| 1619 | Deleting branch |
---|
| 1620 | svn://fcm1/tutorial_svn/tutorial/branches/test/frsn/r1_tutorial ... |
---|
| 1621 | |
---|
| 1622 | Committed 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"><Yes></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> |
---|