[1] | 1 | <?xml version="1.0"?> |
---|
| 2 | <!DOCTYPE CMT [ |
---|
| 3 | <!ENTITY nbsp " "> |
---|
| 4 | <!ENTITY CMTVersion "v1r14"> |
---|
| 5 | <!ENTITY CMTrequirements " <a HREF='#The requirements file'>requirements</a> "> |
---|
| 6 | ]> |
---|
| 7 | |
---|
| 8 | <!-- |
---|
| 9 | |
---|
| 10 | <!ENTITY SYSTEM ".xml"> |
---|
| 11 | |
---|
| 12 | --> |
---|
| 13 | |
---|
| 14 | |
---|
| 15 | <cmt:book |
---|
| 16 | name='CMT' |
---|
| 17 | title='Configuration Management Tool' |
---|
| 18 | version='v1r14' |
---|
| 19 | author='Christian Arnault' |
---|
| 20 | email='arnault@lal.in2p3.fr'> |
---|
| 21 | |
---|
| 22 | <cmt:section title='Presentation'> |
---|
| 23 | |
---|
| 24 | <p>This environment, based on some management conventions and |
---|
| 25 | comprising several shell-based utilities, is an attempt to |
---|
| 26 | formalize software production and especially configuration |
---|
| 27 | management around a <i>package</i>-oriented principle.</p> |
---|
| 28 | |
---|
| 29 | <p>The notion of <i>packages</i> represents hereafter a set of |
---|
| 30 | software components (that may be applications, libraries, |
---|
| 31 | documents, tools etc...) that are to be used for producing a |
---|
| 32 | <i>system</i> or a <i>framework</i>. In such an environment, |
---|
| 33 | several persons are assumed to participate in the development and |
---|
| 34 | the components themselves are either independent or related to |
---|
| 35 | each other.</p> |
---|
| 36 | |
---|
| 37 | <p>The environment provides conventions (for <i>naming</i> |
---|
| 38 | packages, files, directories and for <i>addressing</i> them) and |
---|
| 39 | tools for <i>automating</i> as much as possible the implementation |
---|
| 40 | of these conventions. It permits the <i>description</i> of the |
---|
| 41 | configuration requirements and automatically deduce from the |
---|
| 42 | description the effective set of configuration parameters needed |
---|
| 43 | to operate the packages (typically for <i>building</i> them or |
---|
| 44 | <i>using</i> them).</p> |
---|
| 45 | |
---|
| 46 | <p><b>CMT</b> lays upon some organisational or managerial |
---|
| 47 | principles or mechanisms described below. However, it permits in |
---|
| 48 | many respects the users or the managers to <i>control</i>, |
---|
| 49 | specialize and customize these mechanisms, through |
---|
| 50 | parameterization, strategy control and generic specifications. |
---|
| 51 | |
---|
| 52 | <ul> |
---|
| 53 | <li> Many such packages are produced and maintained. </li> |
---|
| 54 | |
---|
| 55 | <li> The packages may or not be related to each other |
---|
| 56 | (defining a <i>direct acyclic graph</i> of packages - not just |
---|
| 57 | a single tree). </li> |
---|
| 58 | |
---|
| 59 | <li> The concept of package may be extended to implement |
---|
| 60 | structuring or organizing patterns such as those involved in |
---|
| 61 | project management. </li> |
---|
| 62 | |
---|
| 63 | <li> Project management policies and behavioural patterns can |
---|
| 64 | be easily expressed and automated by CMT. </li> |
---|
| 65 | |
---|
| 66 | <li> Each <i>executable application</i> (from now on simply |
---|
| 67 | named <i>applications</i>) either belongs to a particular |
---|
| 68 | package and/or defines its own environment and then makes use |
---|
| 69 | of some other packages. </li> |
---|
| 70 | |
---|
| 71 | <li> Each package can be uniquely identified within the system |
---|
| 72 | or the framework by a <i>name</i> which is usually a short |
---|
| 73 | <i>mnemonic</i> and which may be also used for isolating its |
---|
| 74 | name-space (eg. by <i>prefixing</i> components of the package |
---|
| 75 | by its mnemonic). </li> |
---|
| 76 | |
---|
| 77 | <li> A package installed in this environment may be |
---|
| 78 | <i>exported</i> to a site where the architecture is |
---|
| 79 | reproduced, and as long as the local organisation defined for |
---|
| 80 | the package is preserved through the transport, the |
---|
| 81 | reconstruction procedure will be preserved. Configuration |
---|
| 82 | specifications can be easily provided to cope with machine, |
---|
| 83 | site or system specific features. </li> |
---|
| 84 | |
---|
| 85 | <li> Packages are maintained consistently to their declared |
---|
| 86 | relationships to each other through a <i>version</i> |
---|
| 87 | identification model based on : |
---|
| 88 | |
---|
| 89 | <ul> |
---|
| 90 | |
---|
| 91 | <li> a version is defined with a mnemonic comprising one |
---|
| 92 | to three numbers the <i>major</i> id, the <i>minor</i> id, |
---|
| 93 | and the <i>patch</i> id </li> |
---|
| 94 | |
---|
| 95 | <li> versions with different major ids are said to be |
---|
| 96 | incompatible, </li> |
---|
| 97 | |
---|
| 98 | <li> versions with same major ids but different minor ids |
---|
| 99 | are said to be backward compatible with respect of the |
---|
| 100 | minor id ordering. </li> |
---|
| 101 | |
---|
| 102 | <li> versions differing only by their patch id are said to |
---|
| 103 | be fully compatible with each other. </li> |
---|
| 104 | |
---|
| 105 | </ul> |
---|
| 106 | </li> |
---|
| 107 | |
---|
| 108 | <li> Version control and management schemes (eg. by using |
---|
| 109 | <b>CVS</b>) are usually consistently operated, applying the |
---|
| 110 | conventions on organization and version identification. </li> |
---|
| 111 | |
---|
| 112 | <li> An application that uses one or several packages managed |
---|
| 113 | in this environment should not itself be constrained to be |
---|
| 114 | managed by <b>CMT</b>. The tools should only require a few |
---|
| 115 | exported features (such as a few environment variables) for |
---|
| 116 | referencing any given package. </li> |
---|
| 117 | |
---|
| 118 | <li> similarly, a package maintained in this environment must |
---|
| 119 | be able to use packages that are <i>not</i> managed in this |
---|
| 120 | environment (which are often called <i>external</i> packages). |
---|
| 121 | </li> |
---|
| 122 | |
---|
| 123 | </ul> |
---|
| 124 | </p> |
---|
| 125 | |
---|
| 126 | <p>Following these definitions, the basic configuration management |
---|
| 127 | operations involved here (and serviced by the <b>CMT</b>' tools) |
---|
| 128 | consist of : |
---|
| 129 | |
---|
| 130 | <ul> |
---|
| 131 | |
---|
| 132 | <li> installing the packages in conventional locations so that |
---|
| 133 | they can be referenced by each other, following projects or |
---|
| 134 | teams structuring paradigms, </li> |
---|
| 135 | |
---|
| 136 | <li> describing the configuration &CMTrequirements; for each |
---|
| 137 | package: |
---|
| 138 | |
---|
| 139 | <ul> |
---|
| 140 | |
---|
| 141 | <li> dependencies to other packages, </li> |
---|
| 142 | |
---|
| 143 | <li> Generic behavioural patterns meant to describe |
---|
| 144 | generic configuration items or project specific policies. |
---|
| 145 | </li> |
---|
| 146 | |
---|
| 147 | <li> symbols to be exported to client packages |
---|
| 148 | (environment variables, make macros, etc...) </li> |
---|
| 149 | |
---|
| 150 | <li> components (also named <i>constituents</i>) of the |
---|
| 151 | packages (libraries, applications, generated documents) </li> |
---|
| 152 | |
---|
| 153 | <li> parameterization of the build and test tools </li> |
---|
| 154 | |
---|
| 155 | <li> parameterization of the deployment tools </li> |
---|
| 156 | |
---|
| 157 | <li> Strategies that <b>CMT</b> should follow at run time, |
---|
| 158 | overriding its default ones. </li> |
---|
| 159 | |
---|
| 160 | </ul> |
---|
| 161 | </li> |
---|
| 162 | |
---|
| 163 | <li> deducing the effective configuration parameters from the |
---|
| 164 | &CMTrequirements; so as to |
---|
| 165 | automatize the building phases and the run-time operations and |
---|
| 166 | connections between packages (typically for generating |
---|
| 167 | makefiles, generating compiler and linker options, shared |
---|
| 168 | libraries paths etc...). This construction mechanism follows |
---|
| 169 | customizable strategies (eg. for selecting among possible |
---|
| 170 | alternate versions of available packages). </li> |
---|
| 171 | |
---|
| 172 | </ul> |
---|
| 173 | </p> |
---|
| 174 | |
---|
| 175 | </cmt:section> |
---|
| 176 | |
---|
| 177 | <cmt:section title='The conventions'> |
---|
| 178 | |
---|
| 179 | <p>This environment relies on a set of conventions, mainly for |
---|
| 180 | organizing the directories where packages are maintained and |
---|
| 181 | developed : </p> |
---|
| 182 | |
---|
| 183 | <ul> |
---|
| 184 | |
---|
| 185 | <li> Each package is installed in a standard directory structure |
---|
| 186 | defined at least as follows: |
---|
| 187 | |
---|
| 188 | <cmt:code> |
---|
| 189 | <some root>/<Package mnemonic>/<version mnemonic>/cmt |
---|
| 190 | </cmt:code> |
---|
| 191 | |
---|
| 192 | <p>or / and (<i>obsolescent convention</i>) |
---|
| 193 | |
---|
| 194 | <cmt:code> |
---|
| 195 | <some root>/<Package mnemonic>/<version mnemonic>/mgr |
---|
| 196 | </cmt:code> |
---|
| 197 | </p> |
---|
| 198 | |
---|
| 199 | <p>The <version mnemonic> directory level may also be |
---|
| 200 | omitted, in which case the version information will be stored |
---|
| 201 | inside the cmt directory in a conventional file named |
---|
| 202 | <tt>version.cmt</tt> leading to the following alternate |
---|
| 203 | organization:</p> |
---|
| 204 | |
---|
| 205 | <cmt:code> |
---|
| 206 | <some root>/<Package mnemonic>/cmt/version.cmt |
---|
| 207 | </cmt:code> |
---|
| 208 | |
---|
| 209 | <p>In both cases, the <b>cmt</b> directory holds the main source of information |
---|
| 210 | needed by <b>CMT</b>: the <i>requirements</i> file. All |
---|
| 211 | <b>CMT</b>-related operations are generally executed from this |
---|
| 212 | directory.</p> |
---|
| 213 | |
---|
| 214 | <p>This style of organization should be considered as the |
---|
| 215 | basic (and unique) criterion for a package to be recognized as |
---|
| 216 | a valid <i>CMT package</i>. Any other structuring convention will |
---|
| 217 | be supported by CMT and its operations can always be |
---|
| 218 | customized to follow them</p> |
---|
| 219 | |
---|
| 220 | <p>This structure is a central concept since all relationships |
---|
| 221 | between packages relies on the package identification which |
---|
| 222 | unambiguously and exclusively consists in the duet [ |
---|
| 223 | <i>package-name</i>, <i>package-version</i> ] (or |
---|
| 224 | <i>package-name</i> only when the version directory level is |
---|
| 225 | omitted).</p> |
---|
| 226 | |
---|
| 227 | </li> |
---|
| 228 | |
---|
| 229 | <li> Constructing the internal structure of a package. |
---|
| 230 | |
---|
| 231 | <p>Many other parallel branches (similar to <b>cmt</b>) such |
---|
| 232 | as <b>src</b>, <b>include</b> or <b>test</b> may be freely |
---|
| 233 | added to this list according to the specific needs of each |
---|
| 234 | package. In particular, a set of such parallel branches are |
---|
| 235 | expected to contain <i>binary</i> outputs (those that |
---|
| 236 | compilers, linkers, archive managers or other kinds of code or |
---|
| 237 | pseudo-code generators can produce). Their name always |
---|
| 238 | corresponds to the particular <i>configuration tag</i> used to |
---|
| 239 | produce the output (such as the machine or operating system |
---|
| 240 | type). The <b>CMT</b> toolkit provides, through the <b>cmt |
---|
| 241 | system</b> utility, a default value for this token. An |
---|
| 242 | environment variable (<b>CMTCONFIG</b>) is also assigned to |
---|
| 243 | this value (See the <a href="#Selecting a specific configuration">complete description</a> |
---|
| 244 | of configuration tags).</p> |
---|
| 245 | |
---|
| 246 | <p>Each branch may in addition be freely structured, and there |
---|
| 247 | is no constraint to the complexity of this organization.</p> |
---|
| 248 | |
---|
| 249 | <cmt:image src="Images/InternalPackageStructure.jpg" caption="Structuring a package - A typical example."/> |
---|
| 250 | |
---|
| 251 | </li> |
---|
| 252 | |
---|
| 253 | <p></p> |
---|
| 254 | |
---|
| 255 | <li> Organizing a software base. |
---|
| 256 | |
---|
| 257 | <p>A software base is generally composed of multiple coherent |
---|
| 258 | sets of packages, each installed in its specific root |
---|
| 259 | directory and forming different <i>package areas</i></p> |
---|
| 260 | |
---|
| 261 | <p>There are no constraints on the number of such areas into |
---|
| 262 | which <b>CMT</b> packages are installed. We'll see <a |
---|
| 263 | HREF="#Localizing a package">later</a> on how the different |
---|
| 264 | areas will be declared and identified by <b>CMT</b>.</p> |
---|
| 265 | |
---|
| 266 | <p>examples of such organization can be : </p> |
---|
| 267 | |
---|
| 268 | <cmt:image src="Images/PackageStructure.jpg" caption="Structuring a sofware base."/> |
---|
| 269 | |
---|
| 270 | </li> |
---|
| 271 | </ul> |
---|
| 272 | |
---|
| 273 | </cmt:section> |
---|
| 274 | |
---|
| 275 | <cmt:section title="The architecture of the environment"> |
---|
| 276 | |
---|
| 277 | <p>This environment is based on the fact that one of its packages |
---|
| 278 | (named <b>CMT</b>) provides the basic management |
---|
| 279 | tools. <b>CMT</b>, as a package, has very little specificities and |
---|
| 280 | as such itself obeys the general conventions. The major asymetry |
---|
| 281 | between <b>CMT</b> and all other packages is the fact that once |
---|
| 282 | <b>CMT</b> is installed it implicitly defines one <i>default</i> |
---|
| 283 | root area for other packages (through the environment variable |
---|
| 284 | <b>CMTROOT</b>).</p> |
---|
| 285 | |
---|
| 286 | <p>Then packages may be installed either in this default root area |
---|
| 287 | or in completely different areas. The only constraint in this case |
---|
| 288 | being that their root will have to be specified explicitly. </p> |
---|
| 289 | |
---|
| 290 | <p>A typical configuration for this environment consists of |
---|
| 291 | selecting a public area (generally available from several machines |
---|
| 292 | through an <b>NFS</b> or <b>AFS</b>-like mechanism), installing |
---|
| 293 | the <b>CMT</b> basic package, and then installing user packages in |
---|
| 294 | this default root or in private ones. One frequent semantic given |
---|
| 295 | to this style of configuration is to consider the packages |
---|
| 296 | installed in the area hanging below default root as the publicly |
---|
| 297 | available versions, whereas packages installed elsewhere are |
---|
| 298 | rather meant to be managed in a private context, or in the context |
---|
| 299 | of a non public project. However, dependencies between packages |
---|
| 300 | will always be possible (as long as the system based protections |
---|
| 301 | provide appropriate access rights). </p> |
---|
| 302 | |
---|
| 303 | <p><b>CMT</b> is operated through one main user interface : the |
---|
| 304 | <b>cmt</b> command, which handles the <b>CMT</b> conventions and |
---|
| 305 | which provides a set of services for : </p> |
---|
| 306 | |
---|
| 307 | <ul> |
---|
| 308 | |
---|
| 309 | <li> creating a new package, installing it below the default |
---|
| 310 | root or in a private area. This operation will create or check |
---|
| 311 | the local package directory tree and generate several minimal |
---|
| 312 | scripts (see the description of the <a HREF="#create">create</a> |
---|
| 313 | command), </li> |
---|
| 314 | |
---|
| 315 | <li> describing or monitoring : |
---|
| 316 | |
---|
| 317 | <ul> |
---|
| 318 | |
---|
| 319 | <li> the relationships between the package and other |
---|
| 320 | packages </li> |
---|
| 321 | |
---|
| 322 | <li> the configuration features either specified in the |
---|
| 323 | current package, or imported from related (used) |
---|
| 324 | ones. (symbols, patterns, fragments) </li> |
---|
| 325 | |
---|
| 326 | <li> the constituents of the package in terms of libraries, |
---|
| 327 | executables, or generated documents. </li> |
---|
| 328 | |
---|
| 329 | </ul> |
---|
| 330 | </li> |
---|
| 331 | |
---|
| 332 | <li> automatically generating the reconstruction scripts |
---|
| 333 | (<b>makefiles</b>) from this description. </li> |
---|
| 334 | |
---|
| 335 | <li> recursively acting upon the hierarchy of used packages. |
---|
| 336 | </li> |
---|
| 337 | |
---|
| 338 | </ul> |
---|
| 339 | |
---|
| 340 | <p>Several other utilities are also provided for some specific |
---|
| 341 | activities (such as the automatic production of shared libraries, |
---|
| 342 | <b>C</b> prototypes, management of interactions between <b>CVS</b> |
---|
| 343 | and <b>CMT</b> itself, the management of a similar architecture |
---|
| 344 | for <b>Windows</b> or <b>OS9</b>, setting up protections for |
---|
| 345 | packages (though locks) etc...). </p> |
---|
| 346 | |
---|
| 347 | <cmt:section title="Supported platforms"> |
---|
| 348 | |
---|
| 349 | <b>CMT</b> has been ported and tested on a wide range of |
---|
| 350 | machines/operating systems, including : |
---|
| 351 | |
---|
| 352 | <ul> |
---|
| 353 | |
---|
| 354 | <li> DEC-Unix V4.0 </li> |
---|
| 355 | |
---|
| 356 | <li> HP-UX-10 (several types of platforms) </li> |
---|
| 357 | |
---|
| 358 | <li> AIX-4 </li> |
---|
| 359 | |
---|
| 360 | <li> Solaris </li> |
---|
| 361 | |
---|
| 362 | <li> IRIX </li> |
---|
| 363 | |
---|
| 364 | <li> Several variants of LynxOS </li> |
---|
| 365 | |
---|
| 366 | <li> Linux 2.x </li> |
---|
| 367 | |
---|
| 368 | <li> Windows 95/98/NT/Windows2000 in various environments: |
---|
| 369 | |
---|
| 370 | <ul> |
---|
| 371 | |
---|
| 372 | <li> <b>CYGWIN_NT-5.1</b> environment </li> |
---|
| 373 | |
---|
| 374 | <li> <b>nmake</b> based environment </li> |
---|
| 375 | |
---|
| 376 | <li> <b>MSDev/VisualC 6</b> environment</li> |
---|
| 377 | |
---|
| 378 | <li> <b>MSDev/VisualC 7</b> environment</li> |
---|
| 379 | |
---|
| 380 | </ul> |
---|
| 381 | |
---|
| 382 | </li> |
---|
| 383 | |
---|
| 384 | <li> Darwin (Mac OS X) </li> |
---|
| 385 | |
---|
| 386 | </ul> |
---|
| 387 | |
---|
| 388 | This in particular means that a package developped on one |
---|
| 389 | platform may be re-configured towards any of these platforms |
---|
| 390 | without any change to its configuration description. All |
---|
| 391 | platform specific tools will be dynamically reconfigured and |
---|
| 392 | parameterized transparently. |
---|
| 393 | |
---|
| 394 | </cmt:section> |
---|
| 395 | |
---|
| 396 | </cmt:section> |
---|
| 397 | |
---|
| 398 | |
---|
| 399 | <cmt:section title="Installing a new package"> |
---|
| 400 | |
---|
| 401 | <p>We consider here the installation of a user package. Installing |
---|
| 402 | <b>CMT</b> itself requires special attention and is described in a |
---|
| 403 | dedicated <a href="#Installing CMT for the first time">section</a> |
---|
| 404 | of this document.</p> |
---|
| 405 | |
---|
| 406 | <p>Therefore, we assume that <i>some</i> root directory has been |
---|
| 407 | selected by the system manager, and that <b>CMT</b> is already |
---|
| 408 | installed somewhere. One first has to <i>setup</i> <b>CMT</b> in |
---|
| 409 | order to gain access to the various management utilities, using |
---|
| 410 | for example the shell command: </p> |
---|
| 411 | |
---|
| 412 | <cmt:code> |
---|
| 413 | csh> source /lal/CMT/&CMTVersion;/mgr/setup.csh |
---|
| 414 | |
---|
| 415 | or |
---|
| 416 | |
---|
| 417 | ksh> . /lal/CMT/&CMTVersion;/mgr/setup.sh |
---|
| 418 | |
---|
| 419 | or |
---|
| 420 | |
---|
| 421 | dos> call \lal\CMT\&CMTVersion;\mgr\setup.bat |
---|
| 422 | |
---|
| 423 | </cmt:code> |
---|
| 424 | |
---|
| 425 | <p>Obviously, this operation <b>must</b> be performed (once) |
---|
| 426 | before any other <b>CMT</b> action. Therefore it is often |
---|
| 427 | recommended to install this setup action straight in the |
---|
| 428 | <i>login</i> script. </p> |
---|
| 429 | |
---|
| 430 | <cmt:blockquote> |
---|
| 431 | <i> |
---|
| 432 | |
---|
| 433 | <p> The <i>setup script</i> used in this example is a constant |
---|
| 434 | in the <b>CMT</b> environment : every configured package will |
---|
| 435 | have one such setup script automatically generated and |
---|
| 436 | installed by <b>CMT</b>. It is one important entry point to |
---|
| 437 | any package (and thus to <b>CMT</b> itself). It provides |
---|
| 438 | environment variable definitions and recursive invocations of |
---|
| 439 | setup scripts for related (<i>used</i>) packages (A |
---|
| 440 | corresponding cleanup script is also provided). This script |
---|
| 441 | contains a uniform mechanism for <i>interpreting</i> the &CMTrequirements; file so as to |
---|
| 442 | dynamically define environment variables, aliases for the |
---|
| 443 | package itself and all its used packages. It is constructed |
---|
| 444 | once per package installation by the <b>cmt create</b> |
---|
| 445 | command, or restored by the <b>cmt config</b> command (if it |
---|
| 446 | has been lost).</p> |
---|
| 447 | |
---|
| 448 | </i> |
---|
| 449 | </cmt:blockquote> |
---|
| 450 | |
---|
| 451 | <p> A package is primarily defined by a <i>name</i> and a |
---|
| 452 | <i>version</i> identifier (this duet actually forms the complete |
---|
| 453 | <i>package identifier</i>). These two attributes will be given as |
---|
| 454 | arguments to <b>cmt create</b> such as in the following example : |
---|
| 455 | </p> |
---|
| 456 | |
---|
| 457 | <cmt:code> |
---|
| 458 | csh> cd mydev |
---|
| 459 | csh> cmt create Foo v1 |
---|
| 460 | <i><font face="courier new, courier" COLOR="#007700">------------------------------------------ |
---|
| 461 | Configuring environment for package Foo version v1. |
---|
| 462 | CMT version &CMTVersion;. [1] |
---|
| 463 | Root set to /home/arnault/mydev. |
---|
| 464 | System is Linux-i686 [2] |
---|
| 465 | ------------------------------------------ |
---|
| 466 | Installing the package directory [3] |
---|
| 467 | Installing the version directory |
---|
| 468 | Installing the cmt directory |
---|
| 469 | Installing the src directory |
---|
| 470 | Creating setup scripts. |
---|
| 471 | Creating cleanup scripts. </font></i> |
---|
| 472 | </cmt:code> |
---|
| 473 | |
---|
| 474 | <ol> |
---|
| 475 | |
---|
| 476 | <li>This shows which actual CMT version you are currently using</li> |
---|
| 477 | |
---|
| 478 | <li>This shows the current configuration tag (also available by |
---|
| 479 | the <tt>cmt system</tt> command). In this example this is a |
---|
| 480 | <tt>Linux</tt> machine</li> |
---|
| 481 | |
---|
| 482 | <li>This shows the detailed construction of the complete |
---|
| 483 | directory structure, starting from the top directory which has |
---|
| 484 | the name of the package. Since we are creating a completely new |
---|
| 485 | package, there will be by default only two branches below the |
---|
| 486 | version directory : <tt>cmt</tt> and <tt>src</tt>.</li> |
---|
| 487 | |
---|
| 488 | </ol> |
---|
| 489 | |
---|
| 490 | <p>The package creation occured from the current directory, |
---|
| 491 | creating from there the complete directory tree for this new |
---|
| 492 | package.</p> |
---|
| 493 | |
---|
| 494 | <p>In the next example, we install the package in a completely |
---|
| 495 | different area, by explicitly specifying the path to it as a third |
---|
| 496 | argument to <b>cmt create</b> : </p> |
---|
| 497 | |
---|
| 498 | <cmt:code> |
---|
| 499 | > cmt create Foo v1 /ProjectB |
---|
| 500 | <i><font face="courier new, courier" COLOR="#007700">------------------------------------------ |
---|
| 501 | Configuring environment for package Foo version v1. |
---|
| 502 | CMT version &CMTVersion;. |
---|
| 503 | Root set to /ProjectB. |
---|
| 504 | System is Linux-i686 |
---|
| 505 | ------------------------------------------ |
---|
| 506 | Installing the path directory |
---|
| 507 | Installing the package directory |
---|
| 508 | Installing the version directory |
---|
| 509 | Installing the cmt directory |
---|
| 510 | Installing the src directory |
---|
| 511 | Creating setup scripts. |
---|
| 512 | Creating cleanup scripts. </font></i> |
---|
| 513 | </cmt:code> |
---|
| 514 | |
---|
| 515 | <p></p> |
---|
| 516 | |
---|
| 517 | Several file creations occurred at this level : |
---|
| 518 | |
---|
| 519 | <ul> |
---|
| 520 | |
---|
| 521 | <li> a minimal directory tree for the package, including |
---|
| 522 | <b>src</b> and <b>cmt</b> (the other branches will be installed |
---|
| 523 | when needed or generated at build time). </li> |
---|
| 524 | |
---|
| 525 | <p></p> |
---|
| 526 | |
---|
| 527 | <li> an empty configuration specification file (named |
---|
| 528 | <b>requirements</b>) installed in the <b>cmt</b> branch. </li> |
---|
| 529 | |
---|
| 530 | <p></p> |
---|
| 531 | |
---|
| 532 | <li> A minimal <b>Makefile</b> (on Unix environments only), |
---|
| 533 | containing |
---|
| 534 | |
---|
| 535 | <cmt:code> |
---|
| 536 | include $(CMTROOT)/src/Makefile.header |
---|
| 537 | |
---|
| 538 | include $(CMTROOT)/src/constituents.make |
---|
| 539 | </cmt:code> |
---|
| 540 | |
---|
| 541 | <p></p> |
---|
| 542 | |
---|
| 543 | This <b>Makefile</b> does not need any further modification to |
---|
| 544 | build any of the constituents managed by <b>CMT</b>. The |
---|
| 545 | intermediate makefile fragments will always be re-generated |
---|
| 546 | transparently and automatically at build time. However (and |
---|
| 547 | thanks to this feature), this file will not be modified |
---|
| 548 | <i>anymore</i> by <b>CMT</b> itself. Thus you may insert any |
---|
| 549 | particular make statement you would feel appropriate, |
---|
| 550 | typically when you ask for operations that cannot be taken |
---|
| 551 | into account by <b>CMT</b>. |
---|
| 552 | |
---|
| 553 | </li> |
---|
| 554 | |
---|
| 555 | <p></p> |
---|
| 556 | |
---|
| 557 | <li> A similar minimal <b>NMake</b> file (on Windows |
---|
| 558 | environments only), containing |
---|
| 559 | |
---|
| 560 | <cmt:code> |
---|
| 561 | !include $(CMTROOT)\src\NMakefile.header |
---|
| 562 | |
---|
| 563 | !include $(CMTROOT)\src\constituents.nmake |
---|
| 564 | </cmt:code> |
---|
| 565 | |
---|
| 566 | </li> |
---|
| 567 | |
---|
| 568 | <p></p> |
---|
| 569 | |
---|
| 570 | <li> the setup and cleanup scripts (one flavour for each shell |
---|
| 571 | family). </li> |
---|
| 572 | |
---|
| 573 | </ul> |
---|
| 574 | |
---|
| 575 | One <i>may</i> then setup this new package by running the setup |
---|
| 576 | script (which will not have much effect yet since the requirements |
---|
| 577 | file is empty) : |
---|
| 578 | |
---|
| 579 | <cmt:code> |
---|
| 580 | sh> cd ~/mydev/Foo/v1/cmt |
---|
| 581 | sh> . setup.sh |
---|
| 582 | </cmt:code> |
---|
| 583 | |
---|
| 584 | or |
---|
| 585 | |
---|
| 586 | <cmt:code> |
---|
| 587 | csh> cd ~/mydev/Foo/v1/cmt |
---|
| 588 | csh> source setup.csh |
---|
| 589 | </cmt:code> |
---|
| 590 | |
---|
| 591 | or |
---|
| 592 | |
---|
| 593 | <cmt:code> |
---|
| 594 | dos> cd \mydev\Foo\v1\cmt |
---|
| 595 | dos> call setup.bat |
---|
| 596 | </cmt:code> |
---|
| 597 | |
---|
| 598 | <p>The <b>FOOROOT</b> and <b>FOOCONFIG</b> environment variables |
---|
| 599 | are defined automatically by this operation. </p> |
---|
| 600 | |
---|
| 601 | <p>It should be noted that running the setup script of a package |
---|
| 602 | is not always necessary for building operations. The only |
---|
| 603 | situation where running this script <i>may</i> become useful, is |
---|
| 604 | when an application is to be run, while requiring domain specific |
---|
| 605 | environment variables defined in one of the used packages. Besides |
---|
| 606 | this particular situation, running the setup scripts may not be |
---|
| 607 | needed at all. </p> |
---|
| 608 | |
---|
| 609 | <p>Lastly, this newly created package may be removed by the quite |
---|
| 610 | similar remove command, using exactly the same arguments as those |
---|
| 611 | used for creating the package.</p> |
---|
| 612 | |
---|
| 613 | <cmt:code> |
---|
| 614 | csh> cd mydev |
---|
| 615 | csh> cmt remove Foo v1 |
---|
| 616 | <i><font face="courier new, courier" COLOR="#007700">------------------------------------------ |
---|
| 617 | Removing package Foo version v1. |
---|
| 618 | CMT version &CMTVersion;. |
---|
| 619 | Root set to /home/arnault/mydev. |
---|
| 620 | System is Linux-i686 |
---|
| 621 | ------------------------------------------ |
---|
| 622 | Version v1 has been removed from /home/arnault/mydev/Foo |
---|
| 623 | Package Foo has no more versions. Thus it has been removed.</font></i> |
---|
| 624 | </cmt:code> |
---|
| 625 | |
---|
| 626 | or: |
---|
| 627 | |
---|
| 628 | <cmt:code> |
---|
| 629 | |
---|
| 630 | csh> cmt remove Foo v1 /ProjectB |
---|
| 631 | <i><font face="courier new, courier" COLOR="#007700">------------------------------------------ |
---|
| 632 | Removing package Foo version v1. |
---|
| 633 | CMT version &CMTVersion;. |
---|
| 634 | Root set to /ProjectB. |
---|
| 635 | System is Linux-i686 |
---|
| 636 | ------------------------------------------ |
---|
| 637 | Version v1 has been removed from /ProjectB/Foo |
---|
| 638 | Package Foo has no more versions. Thus it has been removed.</font></i> |
---|
| 639 | </cmt:code> |
---|
| 640 | |
---|
| 641 | <p>So far our package is not very useful since no constituent |
---|
| 642 | (application or library) is installed yet. You can jump to the |
---|
| 643 | section showing how to work on an <a href="#Working on an application">application</a> |
---|
| 644 | or on a <a href="#Working on a library">library</a> |
---|
| 645 | for details on these operations or we can |
---|
| 646 | roughly draw the sequence used to specify and build the simplest |
---|
| 647 | application we can think of as follows:</p> |
---|
| 648 | |
---|
| 649 | <cmt:code> |
---|
| 650 | csh> cd ~/mydev/Foo/v1/cmt |
---|
| 651 | csh> cat >../src/FooTest.c |
---|
| 652 | #include <stdio.h> |
---|
| 653 | |
---|
| 654 | int main () |
---|
| 655 | { |
---|
| 656 | printf ("Hello Foo\n"); |
---|
| 657 | return (0); |
---|
| 658 | } |
---|
| 659 | |
---|
| 660 | csh> vi requirements |
---|
| 661 | ... |
---|
| 662 | application FooTest FooTest.c |
---|
| 663 | csh> gmake |
---|
| 664 | csh> source setup.csh |
---|
| 665 | csh> FooTest.exe |
---|
| 666 | <i><font face="courier new, courier" COLOR="#007700">Hello Foo</font></i> |
---|
| 667 | </cmt:code> |
---|
| 668 | |
---|
| 669 | <p>Directly running the application is possible since the |
---|
| 670 | application has been installed after being built in |
---|
| 671 | an automatic <i>installation area</i> reachable through the |
---|
| 672 | standard <b>PATH</b> environment variable</p> |
---|
| 673 | |
---|
| 674 | <p>This can also be integrated in the build process by providing |
---|
| 675 | the -check option to the application definition:</p> |
---|
| 676 | |
---|
| 677 | <cmt:code> |
---|
| 678 | |
---|
| 679 | csh> cd ../cmt |
---|
| 680 | csh> vi requirements |
---|
| 681 | ... |
---|
| 682 | application FooTest -check FooTest.c |
---|
| 683 | csh> gmake check |
---|
| 684 | <i><font face="courier new, courier" COLOR="#007700">Hello Foo</font></i> |
---|
| 685 | </cmt:code> |
---|
| 686 | |
---|
| 687 | </cmt:section> |
---|
| 688 | |
---|
| 689 | <cmt:section title="Localizing a package"> |
---|
| 690 | |
---|
| 691 | <p>In the next sections, we'll see that packages <i>reference</i> |
---|
| 692 | each other by means of <i>use</i> relationships. Generally |
---|
| 693 | packages are found in different locations, according to the |
---|
| 694 | project - or sub-project - they belong to. <b>CMT</b> provides a |
---|
| 695 | quite flexible mechanism for <i>localizing</i> the referenced |
---|
| 696 | packages. </p> |
---|
| 697 | |
---|
| 698 | <p>A given version of a given package is always referred to by |
---|
| 699 | using a <i>use</i> statement within its <b>&CMTrequirements;</b> |
---|
| 700 | file. This statement should specify the package through three |
---|
| 701 | <i>keys</i> :</p> |
---|
| 702 | |
---|
| 703 | <ul> |
---|
| 704 | |
---|
| 705 | <li> its name (such as <b>Bar</b>) </li> |
---|
| 706 | |
---|
| 707 | <li> its version (such as <b>v7r5</b>) </li> |
---|
| 708 | |
---|
| 709 | <li> optionally its expected absolute location or relative |
---|
| 710 | prefix (also called the <i>use path</i>) |
---|
| 711 | </li> |
---|
| 712 | |
---|
| 713 | </ul> |
---|
| 714 | |
---|
| 715 | <cmt:code> |
---|
| 716 | use Bar v7r5 [1] |
---|
| 717 | </cmt:code> |
---|
| 718 | |
---|
| 719 | <i>or</i> |
---|
| 720 | |
---|
| 721 | <cmt:code> |
---|
| 722 | use Bar v7r5 A [2] |
---|
| 723 | </cmt:code> |
---|
| 724 | |
---|
| 725 | <i>or</i> |
---|
| 726 | |
---|
| 727 | <cmt:code> |
---|
| 728 | use Bar v7r5 /ProjectB/A [3] |
---|
| 729 | </cmt:code> |
---|
| 730 | |
---|
| 731 | <p>Given these keys, the referenced package is looked for |
---|
| 732 | according to a prioritized search list which is (in decreasing |
---|
| 733 | priority order) : </p> |
---|
| 734 | |
---|
| 735 | <ol> |
---|
| 736 | |
---|
| 737 | <li> the absolute access path, if the <i>use path</i> is |
---|
| 738 | absolute (case #3), </li> |
---|
| 739 | |
---|
| 740 | <li> the access paths optionally registered in the configuration |
---|
| 741 | parameter - see below - <b>CMTPATH</b> (and in decreasing |
---|
| 742 | priority, the first element being searched for first), </li> |
---|
| 743 | |
---|
| 744 | <li> the default root. </li> |
---|
| 745 | |
---|
| 746 | <li> the path where the current package is installed, </li> |
---|
| 747 | |
---|
| 748 | </ol> |
---|
| 749 | |
---|
| 750 | <cmt:blockquote> |
---|
| 751 | <i> |
---|
| 752 | |
---|
| 753 | The configuration parameter <b>CMTPATH</b> can be specified |
---|
| 754 | either in the environment variable named <b>CMTPATH</b> or in |
---|
| 755 | <b>.cmtrc</b> files, which can themselves be located either in |
---|
| 756 | the current directory, in the <i>home</i> directory of the |
---|
| 757 | developper or in <b>${CMTROOT}/mgr</b>. In the Windows |
---|
| 758 | environment, this configuration parameter may also be |
---|
| 759 | installed as a <i>Registry</i> under either the keys: |
---|
| 760 | |
---|
| 761 | <ul> |
---|
| 762 | <li> <b>HKEY_LOCAL_MACHINE/Software/CMT/path</b> </li> |
---|
| 763 | <li> <b>HKEY_CURRENT_USER/Software/CMT/path</b> </li> |
---|
| 764 | </ul> |
---|
| 765 | |
---|
| 766 | (A graphical tool vailable in <b>%CMTROOT%\VisualC\install.exe</b> |
---|
| 767 | permits the interactive modification of this list) |
---|
| 768 | </i> |
---|
| 769 | </cmt:blockquote> |
---|
| 770 | |
---|
| 771 | <p>If the <i>path</i> argument is specified as a relative path |
---|
| 772 | (case #2 above) (ie. there is no leading <i>slash</i> character or |
---|
| 773 | it's not a <i>disk</i> on windows machines), it will be used as an |
---|
| 774 | <i>offset</i> to each search case. The search is done starting |
---|
| 775 | from the list specified in the <b>CMTPATH</b> configuration |
---|
| 776 | parameter, then using the default root; and the offset is appended |
---|
| 777 | at each searched location.</p> |
---|
| 778 | |
---|
| 779 | <p>The <b>CMTPATH</b> parameter is thus used as a search list for |
---|
| 780 | the packages, and the individual paths are separated in this list |
---|
| 781 | by <i>colons</i> (<i>semi-colons</i> on Windows). </p> |
---|
| 782 | |
---|
| 783 | <p>As an example, if we specify the <b>CMTPATH</b> parameter as |
---|
| 784 | follows : </p> |
---|
| 785 | |
---|
| 786 | |
---|
| 787 | <cmt:code> |
---|
| 788 | csh> setenv CMTPATH /home/arnault/mydev:/ProjectB |
---|
| 789 | </cmt:code> |
---|
| 790 | |
---|
| 791 | <cmt:code> |
---|
| 792 | sh> export CMTPATH=/home/arnault/mydev:/ProjectB |
---|
| 793 | </cmt:code> |
---|
| 794 | |
---|
| 795 | <cmt:code> |
---|
| 796 | bat> set CMTPATH=/home/arnault/mydev;/ProjectB |
---|
| 797 | </cmt:code> |
---|
| 798 | |
---|
| 799 | or (in a <b>requirements</b> file) |
---|
| 800 | |
---|
| 801 | <cmt:code> |
---|
| 802 | path_append CMTPATH "/home/arnault/mydev" |
---|
| 803 | path_append CMTPATH "/ProjectB" |
---|
| 804 | </cmt:code> |
---|
| 805 | |
---|
| 806 | or (in a <b>.cmtrc</b> file) |
---|
| 807 | |
---|
| 808 | <cmt:code> |
---|
| 809 | CMTPATH=/home/arnault/mydev:/ProjectB |
---|
| 810 | </cmt:code> |
---|
| 811 | |
---|
| 812 | <p>Then a <i>use</i> statement (defined within a given package) |
---|
| 813 | containing : </p> |
---|
| 814 | |
---|
| 815 | <cmt:code> |
---|
| 816 | ... |
---|
| 817 | use Bar v7r5 |
---|
| 818 | use BarA v1 A |
---|
| 819 | </cmt:code> |
---|
| 820 | |
---|
| 821 | (and assuming that the default root is <b>/lal</b>) would look for |
---|
| 822 | the package <b>Bar</b> from : |
---|
| 823 | |
---|
| 824 | <ol> |
---|
| 825 | |
---|
| 826 | <li> <b>/home/arnault/mydev/Bar/v7r5/cmt</b> </li> |
---|
| 827 | |
---|
| 828 | <li> <b>/ProjectB/Bar/v7r5/cmt</b> </li> |
---|
| 829 | |
---|
| 830 | <li> <b>/lal/Bar/v7r5/cmt</b> </li> |
---|
| 831 | |
---|
| 832 | <li> the same path as the current package </li> |
---|
| 833 | |
---|
| 834 | </ol> |
---|
| 835 | |
---|
| 836 | Whereas the package <b>BarA</b> would be searched from : |
---|
| 837 | |
---|
| 838 | <ol> |
---|
| 839 | |
---|
| 840 | <li> <b>/home/arnault/mydev/A/BarA/v1/cmt</b> </li> |
---|
| 841 | |
---|
| 842 | <li> <b>/ProjectB/A/BarA/v1/cmt</b> </li> |
---|
| 843 | |
---|
| 844 | <li> <b>/lal/A/BarA/v1/cmt</b> </li> |
---|
| 845 | |
---|
| 846 | <li> the sub-directory <b>A</b> within the same path as the current |
---|
| 847 | package, </li> |
---|
| 848 | |
---|
| 849 | </ol> |
---|
| 850 | |
---|
| 851 | The packages are searched assuming that the directory hierarchy |
---|
| 852 | below the access paths always follow the convention : |
---|
| 853 | |
---|
| 854 | <ol> |
---|
| 855 | |
---|
| 856 | <li> there is a first directory level exactly named according to |
---|
| 857 | the package name (this is case sensitive), </li> |
---|
| 858 | |
---|
| 859 | <li> then (optionally) the next directory level is named |
---|
| 860 | according to the version tag, </li> |
---|
| 861 | |
---|
| 862 | <li> then there is a branch named <b>cmt</b>, </li> |
---|
| 863 | |
---|
| 864 | <li> lastly there is a <i>requirements</i> file within this |
---|
| 865 | <b>cmt</b> branch. </li> |
---|
| 866 | |
---|
| 867 | </ol> |
---|
| 868 | |
---|
| 869 | Thus the list of access paths is searched for until these |
---|
| 870 | conditions are properly met. |
---|
| 871 | |
---|
| 872 | <p> The actual complete search list can always be visualized by |
---|
| 873 | the command: |
---|
| 874 | |
---|
| 875 | |
---|
| 876 | <cmt:code> |
---|
| 877 | > cmt show path |
---|
| 878 | <i><font face="courier new, courier" COLOR="#007700"># Add path /home/arnault/dev from CMTPATH |
---|
| 879 | # Add path /ProjectB from CMTPATH |
---|
| 880 | # Add path /lal from default path |
---|
| 881 | # |
---|
| 882 | /home/arnault/dev:/ProjectB:/lal</font></i> |
---|
| 883 | </cmt:code> |
---|
| 884 | |
---|
| 885 | </p> |
---|
| 886 | |
---|
| 887 | </cmt:section> |
---|
| 888 | |
---|
| 889 | <cmt:section title="Managing site dependent features - The CMTSITE environment variable"> |
---|
| 890 | |
---|
| 891 | <p>Software bases managed by <b>CMT</b> are often replicated to |
---|
| 892 | multiple geographically distant sites (as opposed to machines |
---|
| 893 | connected through AFS-like WAN). In this kind of situation, some |
---|
| 894 | of the configuration parameters (generally those used for instance |
---|
| 895 | to reference local installations of <i>external</i> software) take |
---|
| 896 | different values. </p> |
---|
| 897 | |
---|
| 898 | <p>The <b>CMTSITE</b> environment variable or <i>registry</i> in |
---|
| 899 | Windows environments, is entirely under the control of the |
---|
| 900 | <i>site</i> manager and can be set up with a value representing |
---|
| 901 | the site (typical values may be <b>LAL</b>, <b>Virgo</b>, |
---|
| 902 | <b>Atlas</b>, <b>LHCb</b>, <b>CERN</b>, etc.). </p> |
---|
| 903 | |
---|
| 904 | <p>This variable, when set, corresponds to a <i>tag</i> which can |
---|
| 905 | be used to select different values for make macros or environment |
---|
| 906 | variables. </p> |
---|
| 907 | |
---|
| 908 | <p>A typical use for this tag is to build up actual values for the |
---|
| 909 | location path of an external software package. Here we take the |
---|
| 910 | example of the Anaphe utility: </p> |
---|
| 911 | |
---|
| 912 | <cmt:code> |
---|
| 913 | macro AnapheTOP "" \ |
---|
| 914 | CERN "/afs/cern.ch/sw/lhcxx" \ |
---|
| 915 | BNL "/afs/rhic/usatlas/offline/external/lhcxx" \ |
---|
| 916 | LBNL "/auto/atlas/sw/lhcxx" |
---|
| 917 | </cmt:code> |
---|
| 918 | |
---|
| 919 | </cmt:section> |
---|
| 920 | |
---|
| 921 | <cmt:section title="Configuring a package"> |
---|
| 922 | |
---|
| 923 | <p>The first ingredient of a proper package configuration is the |
---|
| 924 | set of configuration parameters which has to be specified in a |
---|
| 925 | text file uniquely named <b>&CMTrequirements;</b> and installed in |
---|
| 926 | the <b>cmt</b> branch of the package local tree. </p> |
---|
| 927 | |
---|
| 928 | <p>An empty version of this file is automatically created the |
---|
| 929 | first time the package is installed, and the package manager is |
---|
| 930 | expected to augment it with configuration specifications. </p> |
---|
| 931 | |
---|
| 932 | <p>Many configuration parameters are supposed to be described into |
---|
| 933 | this &CMTrequirements; file - see the <a href="#The requirements file">detailed</a> |
---|
| 934 | syntax specifications here - namely :</p> |
---|
| 935 | |
---|
| 936 | <ul> |
---|
| 937 | |
---|
| 938 | <li> the package information about its author(s) and manager(s) </li> |
---|
| 939 | |
---|
| 940 | <li> the relationships with other packages </li> |
---|
| 941 | |
---|
| 942 | <li> the package constituents (libraries, applications, |
---|
| 943 | documents, etc.) </li> |
---|
| 944 | |
---|
| 945 | <li> the policy patterns to be applied by clients of this |
---|
| 946 | package </li> |
---|
| 947 | |
---|
| 948 | <li> the parameterization of the tools used in the build process |
---|
| 949 | (eg. make macros) </li> |
---|
| 950 | |
---|
| 951 | <li> the parameterization of the run-time activity |
---|
| 952 | (eg. environment variables, search paths, etc.) </li> |
---|
| 953 | |
---|
| 954 | </ul> |
---|
| 955 | |
---|
| 956 | <p>Generally, every such appropriate parameter will be deduced on |
---|
| 957 | demand from the &CMTrequirements; file(s) through the various |
---|
| 958 | query functions available from the <b>cmt</b> main |
---|
| 959 | driver. Therefore there is no systematic package re-configuration |
---|
| 960 | per se, besides the very first time a package is newly installed |
---|
| 961 | in its location (using the <b>cmt create</b> action). </p> |
---|
| 962 | |
---|
| 963 | <p>Query actions (generally provided using the <b>cmt show ...</b> |
---|
| 964 | <a HREF="#show">family</a> of commands) are embedded in the |
---|
| 965 | various productivity tools, such as the setup shell scripts, or |
---|
| 966 | makefile fragment generators. </p> |
---|
| 967 | |
---|
| 968 | <p>These query actions always interpret the set of |
---|
| 969 | &CMTrequirements; files obtained from the current package |
---|
| 970 | <i>and</i> from the packages in the effective <i>used</i> |
---|
| 971 | chain. Symbols, tags and other definitions are then computed and |
---|
| 972 | built up according to inheritance-like mechanisms set up between |
---|
| 973 | used packages. </p> |
---|
| 974 | |
---|
| 975 | <p>Conversely one may say that parameters defined in a |
---|
| 976 | &CMTrequirements; file are meant to be exported to the clients of |
---|
| 977 | the package.</p> |
---|
| 978 | |
---|
| 979 | <p>Other configuration parameters are also optionally inserted |
---|
| 980 | from the <b>HOME</b> and <b>USER</b> <a href=""><i>context</i></a> |
---|
| 981 | requirements files</p> |
---|
| 982 | |
---|
| 983 | <p>Most typical examples of these query functions are: </p> |
---|
| 984 | |
---|
| 985 | <ul> |
---|
| 986 | |
---|
| 987 | <li><b>cmt setup</b> builds a shell command line for setting up |
---|
| 988 | environment variables </li> |
---|
| 989 | |
---|
| 990 | <li><b>cmt show macros</b> construct the effective set of |
---|
| 991 | inherited make macros </li> |
---|
| 992 | |
---|
| 993 | <li><b>cmt show uses</b> gives the ordered and flattened set of |
---|
| 994 | used packages </li> |
---|
| 995 | |
---|
| 996 | <li><b>cmt show constituents</b> lists the package's |
---|
| 997 | constituents </li> |
---|
| 998 | |
---|
| 999 | <li><b>cmt show path</b> lists the effective search path for |
---|
| 1000 | packages. </li> |
---|
| 1001 | |
---|
| 1002 | <li><b>cmt show strategies</b> shows the current setup of |
---|
| 1003 | various functional <b>CMT</b> strategies. </li> |
---|
| 1004 | |
---|
| 1005 | </ul> |
---|
| 1006 | |
---|
| 1007 | </cmt:section> |
---|
| 1008 | |
---|
| 1009 | <cmt:section title="Selecting a specific configuration"> |
---|
| 1010 | |
---|
| 1011 | A configuration describes the conditions in which the package has |
---|
| 1012 | to be built (ie. compiled and linked) or applications can be |
---|
| 1013 | run. This configuration can depend on : |
---|
| 1014 | |
---|
| 1015 | <ul> |
---|
| 1016 | |
---|
| 1017 | <li> the operating system (such as <i>Linux</i>, <i>Windows</i>, |
---|
| 1018 | ...) </li> |
---|
| 1019 | |
---|
| 1020 | <li> the platform (such as <i>Intel</i>, <i>Compaq</i>, |
---|
| 1021 | <i>Sun</i>, etc...) </li> |
---|
| 1022 | |
---|
| 1023 | <li> the choice of the compiler (such as <i>g++</i>, |
---|
| 1024 | <i>egcs</i>, <i>CC</i>, etc...) </li> |
---|
| 1025 | |
---|
| 1026 | <li> options used for compiling (such as <i>optimizer</i>, |
---|
| 1027 | <i>debugger</i>, etc...) or linking </li> |
---|
| 1028 | |
---|
| 1029 | <li> the context specifications (selecting a particular version |
---|
| 1030 | of a firmware, selecting a database server, ...) </li> |
---|
| 1031 | |
---|
| 1032 | <li> the site itself</li> |
---|
| 1033 | |
---|
| 1034 | </ul> |
---|
| 1035 | |
---|
| 1036 | Carefully describing this configuration is essential both for |
---|
| 1037 | maintenance operations (so as to remember the precise conditions |
---|
| 1038 | in which the package was built) and when the development area is |
---|
| 1039 | <i>shared</i> between machines running different operating |
---|
| 1040 | systems, or when a project has to be deployed on several sites. |
---|
| 1041 | |
---|
| 1042 | <cmt:section title="Describing a configuration"> |
---|
| 1043 | |
---|
| 1044 | <p> <b>CMT</b> relies on several complementary conventions or |
---|
| 1045 | mechanisms for this description and the associated |
---|
| 1046 | management. All these conventions rely on the concept of |
---|
| 1047 | <i>configuration tags</i>.</p> |
---|
| 1048 | |
---|
| 1049 | <ul> |
---|
| 1050 | |
---|
| 1051 | <li>A tag is a symbol that describes one aspect of the |
---|
| 1052 | configuration.</li> |
---|
| 1053 | |
---|
| 1054 | <li>A tag can be <i>active</i> when the corresponding aspect |
---|
| 1055 | of the configuration is true or <i>inactive</i> otherwise</li> |
---|
| 1056 | |
---|
| 1057 | <li>The set of active tags represents the complete |
---|
| 1058 | configuration known by CMT, and can be visualized with the |
---|
| 1059 | <b>cmt show tags</b> command</li> |
---|
| 1060 | |
---|
| 1061 | </ul> |
---|
| 1062 | |
---|
| 1063 | <ol> |
---|
| 1064 | |
---|
| 1065 | <li>Some aspects of the configuration - and the associated tags - |
---|
| 1066 | are automatically deduced from some standard environment |
---|
| 1067 | variables that the user is expected to specify (typically using |
---|
| 1068 | shell commands):<p></p> |
---|
| 1069 | |
---|
| 1070 | <p></p> |
---|
| 1071 | <ul> |
---|
| 1072 | |
---|
| 1073 | <li><b>CMTCONFIG</b> describes the current settings for producing |
---|
| 1074 | binary objects. One default value is provided automatically by |
---|
| 1075 | CMT, but generally project will override it to apply specific |
---|
| 1076 | conventions. |
---|
| 1077 | |
---|
| 1078 | <cmt:blockquote>The default value is computed by CMT in the |
---|
| 1079 | ${CMTROOT}/mgr/cmt_system.sh shell script. |
---|
| 1080 | |
---|
| 1081 | <p>This script automatically builds a value characterizing |
---|
| 1082 | both the machine type and the operating system type (using a |
---|
| 1083 | mixing of the <b>uname</b> standard <b>UNIX</b> command with |
---|
| 1084 | various operating system specific definitions such as the |
---|
| 1085 | <b>AFS</b> based <b>fs sysname</b> command)</p> |
---|
| 1086 | </cmt:blockquote><p></p></li> |
---|
| 1087 | |
---|
| 1088 | <li><b>CMTSITE</b> characterizes the current site. Its syntax is |
---|
| 1089 | completely free<p></p></li> |
---|
| 1090 | |
---|
| 1091 | <li><b>CMTEXTRATAGS</b> may contain a space-separated list of |
---|
| 1092 | additional tags to systematically activate</li> |
---|
| 1093 | |
---|
| 1094 | </ul> |
---|
| 1095 | <p></p> |
---|
| 1096 | |
---|
| 1097 | <cmt:blockquote><i>Note that the <b>CMTBIN</b> variable which |
---|
| 1098 | represents the current binary installation of CMT itself does |
---|
| 1099 | NOT correspond to any tag.</i></cmt:blockquote> |
---|
| 1100 | |
---|
| 1101 | <p></p> |
---|
| 1102 | </li> |
---|
| 1103 | |
---|
| 1104 | <li> |
---|
| 1105 | Some aspects of the configuration represents the implicit |
---|
| 1106 | knowledge CMT gets of the current context: |
---|
| 1107 | |
---|
| 1108 | <p></p> |
---|
| 1109 | <ul> |
---|
| 1110 | |
---|
| 1111 | <li>The value given by the <i>uname</i> standard Unix facility |
---|
| 1112 | is always a valid configuration tag. (eg. <b>Linux</b>)</li> |
---|
| 1113 | |
---|
| 1114 | <li>The current major version id of CMT is a valid tag and |
---|
| 1115 | takes the form <b>CMTv<n></b> (eg. <b>CMTv1</b>)</li> |
---|
| 1116 | |
---|
| 1117 | <li>The current minor version id of CMT is a valid tag and |
---|
| 1118 | takes the form <b>CMTr<n></b> (eg. <b>CMTr14</b>)</li> |
---|
| 1119 | |
---|
| 1120 | <li>The current patch id of CMT is a valid tag and takes the |
---|
| 1121 | form <b>CMTp<n></b> (eg. <b>CMTp20030616</b>)</li> |
---|
| 1122 | |
---|
| 1123 | </ul> |
---|
| 1124 | |
---|
| 1125 | <p></p> |
---|
| 1126 | </li> |
---|
| 1127 | |
---|
| 1128 | <li> |
---|
| 1129 | User defined tags can be explicitly or implicitly activated: |
---|
| 1130 | |
---|
| 1131 | <p></p> |
---|
| 1132 | <ul> |
---|
| 1133 | |
---|
| 1134 | <li>explicitly from the <b>cmt</b> command line, using the |
---|
| 1135 | <b>-tag=<tag-list></b> option </li> |
---|
| 1136 | |
---|
| 1137 | <li>explictly from requirements files using the <b>apply_tag |
---|
| 1138 | <tag></b> syntax</li> |
---|
| 1139 | |
---|
| 1140 | <li> implicitly from requirements files using the tag |
---|
| 1141 | association syntax, when a tag is associated with an otherwise |
---|
| 1142 | activated tag. One example is the <b>Unix</b> tag associated |
---|
| 1143 | by CMT itself with most Unix variants </li> |
---|
| 1144 | |
---|
| 1145 | </ul> |
---|
| 1146 | </li> |
---|
| 1147 | |
---|
| 1148 | </ol> |
---|
| 1149 | |
---|
| 1150 | The minimal tag set available from CMT can be visualized as |
---|
| 1151 | follows (note that the exact output will not necessarly be the |
---|
| 1152 | one presented in this document according to the context |
---|
| 1153 | effectively used): |
---|
| 1154 | |
---|
| 1155 | <cmt:code> |
---|
| 1156 | > cd ${CMTROOT} |
---|
| 1157 | > cmt show tags |
---|
| 1158 | CMTv1 (from CMTVERSION) [1] |
---|
| 1159 | CMTr14 (from CMTVERSION) [1] |
---|
| 1160 | CMTp20030616 (from CMTVERSION) [1] |
---|
| 1161 | Linux (from uname) package CMT implies [Unix] [2] |
---|
| 1162 | i386_linux24 (from CMTCONFIG) [3] |
---|
| 1163 | CERN (from CMTSITE) [4] |
---|
| 1164 | Default (from Default) |
---|
| 1165 | Unix (from package CMT) [5] |
---|
| 1166 | </cmt:code> |
---|
| 1167 | |
---|
| 1168 | <ol> |
---|
| 1169 | |
---|
| 1170 | <li>Implicit tags deduced from the current version of CMT</li> |
---|
| 1171 | <li>Implicit tag obtained from the uname command (note that there is an associated tag defined here)</li> |
---|
| 1172 | <li>The current value of CMTCONFIG</li> |
---|
| 1173 | <li>The current value of CMTSITE</li> |
---|
| 1174 | <li>A indirectly activated tag (associated with another active tag)</li> |
---|
| 1175 | |
---|
| 1176 | </ol> |
---|
| 1177 | |
---|
| 1178 | </cmt:section> |
---|
| 1179 | |
---|
| 1180 | <cmt:section title="Defining the user tags"> |
---|
| 1181 | |
---|
| 1182 | <p>The user configuration tags can generally be specified though |
---|
| 1183 | various complementary means:</p> |
---|
| 1184 | |
---|
| 1185 | <ul> |
---|
| 1186 | |
---|
| 1187 | <li>CMTSITE and CMTCONFIG can be specified using standard |
---|
| 1188 | shell commands (setenv, export, set)</li> |
---|
| 1189 | |
---|
| 1190 | <cmt:code> |
---|
| 1191 | sh> export CMTSITE=CERN |
---|
| 1192 | </cmt:code> |
---|
| 1193 | |
---|
| 1194 | <p></p> |
---|
| 1195 | |
---|
| 1196 | <li>CMTSITE and CMTCONFIG can alternatively be specified using |
---|
| 1197 | the <b>set</b> statement in a requirements file</li> |
---|
| 1198 | |
---|
| 1199 | <cmt:code> |
---|
| 1200 | set CMTSITE "CERN" |
---|
| 1201 | set CMTCONFIG "${CMTBIN}" sun "Solaris-CC-dbg" |
---|
| 1202 | </cmt:code> |
---|
| 1203 | |
---|
| 1204 | <p></p> |
---|
| 1205 | |
---|
| 1206 | <li> Additional tags may also be associated with other tags, |
---|
| 1207 | using the <b>tag</b> statement (in a requirements file): |
---|
| 1208 | |
---|
| 1209 | <cmt:code> |
---|
| 1210 | tag newtag tag1 tag2 tag3 |
---|
| 1211 | </cmt:code> |
---|
| 1212 | |
---|
| 1213 | which means that: |
---|
| 1214 | |
---|
| 1215 | <ul> |
---|
| 1216 | |
---|
| 1217 | <li><b>newtag</b> defines a tag</li> |
---|
| 1218 | |
---|
| 1219 | <li>when <b>newtag</b> is active, then both tag1, tag2 and |
---|
| 1220 | tag3 are simultaneously active</li> |
---|
| 1221 | |
---|
| 1222 | </ul> |
---|
| 1223 | </li> |
---|
| 1224 | |
---|
| 1225 | <p></p> |
---|
| 1226 | |
---|
| 1227 | <li> |
---|
| 1228 | Tags may be declared as <i>exclusive</i> using the <b>tag_exclude</b> syntax. |
---|
| 1229 | |
---|
| 1230 | <cmt:code> |
---|
| 1231 | tag_exclude debug optimized |
---|
| 1232 | </cmt:code> |
---|
| 1233 | |
---|
| 1234 | This example implies that the two tags <b>debug</b> and |
---|
| 1235 | <b>optimized</b> should never become active simultaneously. |
---|
| 1236 | |
---|
| 1237 | </li> |
---|
| 1238 | |
---|
| 1239 | <p></p> |
---|
| 1240 | |
---|
| 1241 | <li> |
---|
| 1242 | Tags are assigned priorities according to the way they have |
---|
| 1243 | been defined. The priority is particularly useful for |
---|
| 1244 | specifying exclusion. The tag association promotes the |
---|
| 1245 | priority of the associated tags to the priority of the |
---|
| 1246 | defining tag. |
---|
| 1247 | |
---|
| 1248 | The following decreasing priorities are currently defined by |
---|
| 1249 | CMT: |
---|
| 1250 | |
---|
| 1251 | <p></p> |
---|
| 1252 | |
---|
| 1253 | <ol> |
---|
| 1254 | |
---|
| 1255 | <li>tag specified in the command line using the -tag=<tag-list> option</li> |
---|
| 1256 | <li>tag deduced from CMTCONFIG</li> |
---|
| 1257 | <li>tag defined in a requirements file using the <b>tag</b> syntax</li> |
---|
| 1258 | <li>tag deduced from CMTSITE</li> |
---|
| 1259 | <li>tag deduced from <i>uname</i></li> |
---|
| 1260 | <li>tags deduced from the version of CMT</li> |
---|
| 1261 | |
---|
| 1262 | </ol> |
---|
| 1263 | |
---|
| 1264 | </li> |
---|
| 1265 | |
---|
| 1266 | </ul> |
---|
| 1267 | |
---|
| 1268 | </cmt:section> |
---|
| 1269 | |
---|
| 1270 | <cmt:section title="Activating tags"> |
---|
| 1271 | |
---|
| 1272 | By default, only CMTCONFIG, <i>uname</i> and CMTSITE (also named |
---|
| 1273 | system tags) are active at any time. |
---|
| 1274 | |
---|
| 1275 | <p>Then it is possible to <i>activate</i> alternate tags through |
---|
| 1276 | the following arguments to <i>any</i> cmt command:</p> |
---|
| 1277 | |
---|
| 1278 | <ul> |
---|
| 1279 | |
---|
| 1280 | <li> |
---|
| 1281 | -tag=<tag-list> |
---|
| 1282 | |
---|
| 1283 | <p> will cleanup the complete current tag set, and |
---|
| 1284 | activate the new tags (the system tags are restored). |
---|
| 1285 | </p> |
---|
| 1286 | |
---|
| 1287 | </li> |
---|
| 1288 | |
---|
| 1289 | <li> |
---|
| 1290 | -tag_add=<tag-list> |
---|
| 1291 | |
---|
| 1292 | <p> will add to the current tag set the tags |
---|
| 1293 | specified in the comma separated list </p> |
---|
| 1294 | |
---|
| 1295 | </li> |
---|
| 1296 | |
---|
| 1297 | <li> |
---|
| 1298 | -tag_remove=<tag-list> |
---|
| 1299 | |
---|
| 1300 | <p>will remove from the current tag set the tags specified |
---|
| 1301 | in the comma separated list</p> |
---|
| 1302 | |
---|
| 1303 | </li> |
---|
| 1304 | </ul> |
---|
| 1305 | |
---|
| 1306 | <cmt:blockquote> |
---|
| 1307 | |
---|
| 1308 | Beware that giving these arguments generally make the selected |
---|
| 1309 | tag set active only during the selected command. Therefore two |
---|
| 1310 | different CMT commands run with different tag sets will |
---|
| 1311 | generally yield different results. However it's often useful to |
---|
| 1312 | persistify a tag set. This can be obtained by the following |
---|
| 1313 | mechanisms: |
---|
| 1314 | |
---|
| 1315 | <ol> |
---|
| 1316 | |
---|
| 1317 | <li> |
---|
| 1318 | Forcing a tag in a requirements file using the <b>apply_tag</b> syntax |
---|
| 1319 | |
---|
| 1320 | <p></p> |
---|
| 1321 | |
---|
| 1322 | Eg the following syntax installed in a requirements file |
---|
| 1323 | will force the tag <b>foo</b>: |
---|
| 1324 | |
---|
| 1325 | <cmt:code> |
---|
| 1326 | tag_apply foo |
---|
| 1327 | </cmt:code> |
---|
| 1328 | |
---|
| 1329 | <cmt:code> |
---|
| 1330 | > cmt show tags |
---|
| 1331 | CMTv1 (from CMTVERSION) |
---|
| 1332 | CMTr14 (from CMTVERSION) |
---|
| 1333 | CMTp0 (from CMTVERSION) |
---|
| 1334 | Linux (from uname) |
---|
| 1335 | Linux-i686 (from CMTCONFIG) package CMT implies [Linux] |
---|
| 1336 | Default (from Default) |
---|
| 1337 | foo (from package Foo) |
---|
| 1338 | </cmt:code> |
---|
| 1339 | |
---|
| 1340 | </li> |
---|
| 1341 | |
---|
| 1342 | <li> |
---|
| 1343 | Implying a tag from another one using the tag association syntax |
---|
| 1344 | |
---|
| 1345 | <cmt:code> |
---|
| 1346 | tag Linux foo |
---|
| 1347 | </cmt:code> |
---|
| 1348 | |
---|
| 1349 | <cmt:code> |
---|
| 1350 | > cmt show tags |
---|
| 1351 | CMTv1 (from CMTVERSION) |
---|
| 1352 | CMTr14 (from CMTVERSION) |
---|
| 1353 | CMTp0 (from CMTVERSION) |
---|
| 1354 | Linux (from uname) package Foo implies [foo] |
---|
| 1355 | Linux-i686 (from CMTCONFIG) package CMT implies [Linux] |
---|
| 1356 | Default (from Default) |
---|
| 1357 | foo (from package Foo) |
---|
| 1358 | </cmt:code> |
---|
| 1359 | |
---|
| 1360 | </li> |
---|
| 1361 | |
---|
| 1362 | <li> |
---|
| 1363 | Through conventionally encoded values of CMTCONFIG |
---|
| 1364 | |
---|
| 1365 | <cmt:code> |
---|
| 1366 | tag Linux-foo Linux foo |
---|
| 1367 | </cmt:code> |
---|
| 1368 | |
---|
| 1369 | <cmt:code> |
---|
| 1370 | > export CMTCONFIG=Linux-foo |
---|
| 1371 | > cmt show tags |
---|
| 1372 | CMTv1 (from CMTVERSION) |
---|
| 1373 | CMTr14 (from CMTVERSION) |
---|
| 1374 | CMTp0 (from CMTVERSION) |
---|
| 1375 | Linux (from uname) |
---|
| 1376 | Linux-foo (from CMTCONFIG) package Foo implies [Linux foo] |
---|
| 1377 | Default (from Default) |
---|
| 1378 | Linux-i686 (from package CMT) package CMT implies [Linux] |
---|
| 1379 | foo (from package Foo) |
---|
| 1380 | </cmt:code> |
---|
| 1381 | |
---|
| 1382 | </li> |
---|
| 1383 | |
---|
| 1384 | </ol> |
---|
| 1385 | |
---|
| 1386 | </cmt:blockquote> |
---|
| 1387 | |
---|
| 1388 | <p>The current active tag set can always be visualized using the |
---|
| 1389 | <b>cmt show tags</b> command.</p> |
---|
| 1390 | |
---|
| 1391 | <cmt:code> |
---|
| 1392 | > cmt show tags |
---|
| 1393 | <i><font face="courier new, courier" COLOR="#007700">CMTv1 (from CMTVERSION) |
---|
| 1394 | CMTr14 (from CMTVERSION) |
---|
| 1395 | CMTp0 (from CMTVERSION) |
---|
| 1396 | Linux (from uname) |
---|
| 1397 | Linux-i686 (from CMTCONFIG) package CMT implies [Linux] |
---|
| 1398 | Default (from Default) |
---|
| 1399 | </font></i> |
---|
| 1400 | > cmt -tag_add=tag1,tag2,tag3 show tags |
---|
| 1401 | <font face="courier new, courier" COLOR="#007700">CMTv1 (from CMTVERSION) |
---|
| 1402 | CMTr14 (from CMTVERSION) |
---|
| 1403 | CMTp0 (from CMTVERSION) |
---|
| 1404 | Linux (from uname) |
---|
| 1405 | Linux-i686 (from CMTCONFIG) package CMT implies [Linux] |
---|
| 1406 | tag1 (from arguments) |
---|
| 1407 | tag2 (from arguments) |
---|
| 1408 | tag3 (from arguments) |
---|
| 1409 | Default (from Default)</font> |
---|
| 1410 | </cmt:code> |
---|
| 1411 | |
---|
| 1412 | <p>Typical usages of those extra tags are:</p> |
---|
| 1413 | |
---|
| 1414 | <ul> |
---|
| 1415 | |
---|
| 1416 | <li> when using special compiler options (e.g. optimization, |
---|
| 1417 | debugging, ...) </li> |
---|
| 1418 | |
---|
| 1419 | <li> for switching to different compilers (e.g. <b>gcc</b> |
---|
| 1420 | versus the native compiler) </li> |
---|
| 1421 | |
---|
| 1422 | <li> when one uses a special debugging environment such as |
---|
| 1423 | <b>Insure</b> or <b>Purify</b> </li> |
---|
| 1424 | |
---|
| 1425 | <li> when using special system specific features (such as |
---|
| 1426 | whether one uses thread-safe algorithms or not) </li> |
---|
| 1427 | |
---|
| 1428 | </ul> |
---|
| 1429 | |
---|
| 1430 | <p>All symbol definitions providing specific values triggered by |
---|
| 1431 | the active selectors will be selected, such as in:</p> |
---|
| 1432 | |
---|
| 1433 | <cmt:code> |
---|
| 1434 | macro_append cppflags "" \ |
---|
| 1435 | debug " -g " |
---|
| 1436 | </cmt:code> |
---|
| 1437 | |
---|
| 1438 | </cmt:section> |
---|
| 1439 | |
---|
| 1440 | </cmt:section> |
---|
| 1441 | |
---|
| 1442 | <cmt:section title="Working on a package"> |
---|
| 1443 | |
---|
| 1444 | <p>In this section, we'll see, through a quite simple scenario, |
---|
| 1445 | the typical operations generally needed for installing, defining |
---|
| 1446 | and building a package. We are continuing the <a |
---|
| 1447 | href="#Installing a new package">example</a> of the <b>Foo</b> |
---|
| 1448 | package already used in this document. </p> |
---|
| 1449 | |
---|
| 1450 | <cmt:section title="Working on a library"> |
---|
| 1451 | |
---|
| 1452 | <p>Let's assume, as a first example, that the <b>Foo</b> package |
---|
| 1453 | <i>is</i> originally composed of one library <b>libFoo.a</b> |
---|
| 1454 | itself made from two sources : <b>FooA.c</b> and |
---|
| 1455 | <b>FooB.c</b>. A shared flavour of the library <b>libFoo.so</b> |
---|
| 1456 | or <b>libFoo.sl</b> or <b>libFoo.dll</b>) is also foreseen.</p> |
---|
| 1457 | |
---|
| 1458 | <p> The minimal set of branches provided by <b>CMT</b> (once the |
---|
| 1459 | <b>cmt create</b> operation has been performed) for a package |
---|
| 1460 | includes <b>src</b> for the sources and <b>cmt</b> for the |
---|
| 1461 | <i>Makefiles</i> and other scripts.</p> |
---|
| 1462 | |
---|
| 1463 | <p> The various tools <b>CMT</b> provide will be fully exploited |
---|
| 1464 | if one respects the roles these branches have to play. However |
---|
| 1465 | it is always possible to extend the default understanding |
---|
| 1466 | <b>CMT</b> gets on the package by appropriate modifiers |
---|
| 1467 | (typically by overriding <a href="#Standard macros predefined in CMT">standard</a> macros). </p> |
---|
| 1468 | |
---|
| 1469 | <p> Assuming the conventional usage is selected, the steps |
---|
| 1470 | described in this section can be undertaken in order to actually |
---|
| 1471 | develop a software package. </p> |
---|
| 1472 | |
---|
| 1473 | <p> We first have to create the two source files into the |
---|
| 1474 | <b>src</b> branch (typically using our favourite text |
---|
| 1475 | editor). Then a description of the expected library (ie. built |
---|
| 1476 | from these two source files) will be entered into the |
---|
| 1477 | <b>requirements</b> file. The minimal syntax required in our |
---|
| 1478 | example will be :</p> |
---|
| 1479 | |
---|
| 1480 | <cmt:code> |
---|
| 1481 | csh> cd ../cmt |
---|
| 1482 | csh> vi requirements (1) |
---|
| 1483 | library Foo FooA.cxx FooB.cxx |
---|
| 1484 | </cmt:code> |
---|
| 1485 | |
---|
| 1486 | <ol> |
---|
| 1487 | |
---|
| 1488 | <li> the <b>&CMTrequirements;</b> |
---|
| 1489 | file located in the <b>cmt</b> |
---|
| 1490 | branch of the package receives the description of this |
---|
| 1491 | <i>library</i> component. This is done using one |
---|
| 1492 | <b>library</b> statement. </li> |
---|
| 1493 | |
---|
| 1494 | </ol> |
---|
| 1495 | |
---|
| 1496 | <p>The <b>cmt create</b> command had generated a simple |
---|
| 1497 | <i>Makefile</i> (or <b>NMake</b> file) which is generaly |
---|
| 1498 | sufficient for all standard operations, since <b>CMT</b> |
---|
| 1499 | continuously and transparently manages the automatic |
---|
| 1500 | reconstruction of all intermediate makefile fragments. We |
---|
| 1501 | therefore simply and immediately execute gmake as follows:</p> |
---|
| 1502 | |
---|
| 1503 | <cmt:code> |
---|
| 1504 | ...v1/cmt> gmake QUIET=1 |
---|
| 1505 | <i><font face="courier new, courier" COLOR="#007700">------> (Makefile.header) Rebuilding constituents.make |
---|
| 1506 | ------> (constituents.make) Rebuilding setup.make Linux-i686.make [1] |
---|
| 1507 | setup.make ok |
---|
| 1508 | ------> (constituents.make) Rebuilding library links |
---|
| 1509 | ------> (constituents.make) all done |
---|
| 1510 | ------> (constituents.make) Building Foo.make [2] |
---|
| 1511 | Library Foo |
---|
| 1512 | ------> (constituents.make) Starting Foo |
---|
| 1513 | ------> (Foo.make) Rebuilding ../Linux-i686/Foo_dependencies.make [3] |
---|
| 1514 | rebuilding ../Linux-i686/FooA.o |
---|
| 1515 | rebuilding ../Linux-i686/FooB.o |
---|
| 1516 | rebuilding library |
---|
| 1517 | ------> Foo : library ok |
---|
| 1518 | ------> Foo ok |
---|
| 1519 | Installing library libFoo.so into /home/arnault/mydev/InstallArea/Linux-i686/lib |
---|
| 1520 | installation done [4] |
---|
| 1521 | ------> (constituents.make) Foo done |
---|
| 1522 | all ok. |
---|
| 1523 | Linux-i686.make ok |
---|
| 1524 | gmake[2]: `config' is up to date. |
---|
| 1525 | gmake[2]: `all' is up to date.</font></i> |
---|
| 1526 | </cmt:code> |
---|
| 1527 | |
---|
| 1528 | <ol> |
---|
| 1529 | |
---|
| 1530 | <li> Some intermediate makefile fragments are automatically |
---|
| 1531 | built to reflect the current effective set of Makefile macros |
---|
| 1532 | deduced from the configuration (read from the <b> |
---|
| 1533 | &CMTrequirements;</b> file). These fragments are automatically |
---|
| 1534 | rebuilt (if needed) each time one of the |
---|
| 1535 | <b>&CMTrequirements;</b> file changes. </li> |
---|
| 1536 | |
---|
| 1537 | <li> Each component of the package (be it a particular |
---|
| 1538 | <i>library</i> or a particular <i>executable</i>) will have |
---|
| 1539 | its own <i>makefile</i> fragment (named |
---|
| 1540 | <b>../${CMTCONFIG}/<name>.[n]mak[e]</b>). This dedicated |
---|
| 1541 | <i>makefile</i> takes care of filling up the library and |
---|
| 1542 | creating the shared library (on the systems where this is |
---|
| 1543 | possible). </li> |
---|
| 1544 | |
---|
| 1545 | <li> The directory which is used for the binaries (i.e. the |
---|
| 1546 | results of compilation or the libraries) has been |
---|
| 1547 | automatically created by a generic target (<tt>dirs</tt>) |
---|
| 1548 | which is defined within <b>[N]Makefile.header</b>. A new |
---|
| 1549 | binary directory will be created each time a new value of the |
---|
| 1550 | <b>CMTCONFIG</b> environment variable is defined or a |
---|
| 1551 | <i>tag</i> is provided on the command line to <b>make</b>. |
---|
| 1552 | </li> |
---|
| 1553 | |
---|
| 1554 | <li> An automatic installation mechanism is applied for all |
---|
| 1555 | successfully built binaries. </li> |
---|
| 1556 | |
---|
| 1557 | </ol> |
---|
| 1558 | |
---|
| 1559 | or, for nmake: |
---|
| 1560 | |
---|
| 1561 | <cmt:code> |
---|
| 1562 | ...v1/cmt> nmake /f nmake |
---|
| 1563 | </cmt:code> |
---|
| 1564 | |
---|
| 1565 | <p>This mechanism relies on some conventional <i>macros</i> and |
---|
| 1566 | incremental <i>targets</i> used within the specific |
---|
| 1567 | makefiles. Some are automatically generated, some have to be |
---|
| 1568 | specified in user packages. It's quite important to understand |
---|
| 1569 | the list of possible customization macros, since this is the |
---|
| 1570 | main communication medium between <b>CMT</b> and the package |
---|
| 1571 | manager. See the complete |
---|
| 1572 | <a href="#Standard macros predefined in CMT">table</a> |
---|
| 1573 | of those conventional macro when you want to |
---|
| 1574 | interact with the standard CMT behaviour. </p> |
---|
| 1575 | |
---|
| 1576 | </cmt:section> |
---|
| 1577 | |
---|
| 1578 | <cmt:section title="Working on an application"> |
---|
| 1579 | |
---|
| 1580 | <p>Assume we now want to add a test program to our |
---|
| 1581 | development. Then we create a <b>FooTest.cxx</b> source, and |
---|
| 1582 | generate the associated makefile (specifying that it will be an |
---|
| 1583 | executable instead of a library) : </p> |
---|
| 1584 | |
---|
| 1585 | <cmt:code> |
---|
| 1586 | csh> cd ../src |
---|
| 1587 | csh> emacs FooTest.cxx |
---|
| 1588 | ... |
---|
| 1589 | csh> cd ../cmt |
---|
| 1590 | csh> vi requirements |
---|
| 1591 | ... |
---|
| 1592 | application FooTest FooTest.cxx |
---|
| 1593 | </cmt:code> |
---|
| 1594 | |
---|
| 1595 | So that we may simply build the complete stuff by running : |
---|
| 1596 | |
---|
| 1597 | <cmt:code> |
---|
| 1598 | > [g]make QUIET=1 |
---|
| 1599 | <i><font face="courier new, courier" COLOR="#007700">------> (Makefile.header) Rebuilding constituents.make |
---|
| 1600 | ------> (constituents.make) Rebuilding setup.make Linux-i686.make |
---|
| 1601 | setup.make ok |
---|
| 1602 | ------> (constituents.make) Rebuilding library links |
---|
| 1603 | ------> (constituents.make) all done |
---|
| 1604 | ------> (constituents.make) Building Foo.make |
---|
| 1605 | Library Foo |
---|
| 1606 | ------> (constituents.make) Starting Foo |
---|
| 1607 | ------> Foo : library ok |
---|
| 1608 | ------> Foo ok |
---|
| 1609 | installation done |
---|
| 1610 | ------> (constituents.make) Foo done |
---|
| 1611 | ------> (constituents.make) Building FooTest.make |
---|
| 1612 | Application FooTest |
---|
| 1613 | ------> (constituents.make) Starting FooTest |
---|
| 1614 | ------> (FooTest.make) Rebuilding ../Linux-i686/FooTest_dependencies.make |
---|
| 1615 | rebuilding ../Linux-i686/FooTest.o |
---|
| 1616 | rebuilding ../Linux-i686/FooTest.exe |
---|
| 1617 | ------> FooTest ok |
---|
| 1618 | Installing application FooTest.exe into /home/arnault/mydev/InstallArea/Linux-i686/bin |
---|
| 1619 | installation done |
---|
| 1620 | ------> (constituents.make) FooTest done |
---|
| 1621 | all ok. |
---|
| 1622 | Linux-i686.make ok |
---|
| 1623 | gmake[2]: `config' is up to date. |
---|
| 1624 | gmake[2]: `all' is up to date.</font></i> |
---|
| 1625 | </cmt:code> |
---|
| 1626 | |
---|
| 1627 | Which shows that a program <b>FooTest.exe</b> has been built |
---|
| 1628 | from our sources. Assuming now that this program needs to access |
---|
| 1629 | the <b>Foo</b> library, we'll just add the following definition |
---|
| 1630 | in the <b>&CMTrequirements;</b> |
---|
| 1631 | file : |
---|
| 1632 | |
---|
| 1633 | <cmt:code> |
---|
| 1634 | ... |
---|
| 1635 | macro Foo_linkopts " -lFoo " \ |
---|
| 1636 | WIN32 " $(FOOROOT)/$(Foo_tag)/Foo.lib " |
---|
| 1637 | ... |
---|
| 1638 | </cmt:code> |
---|
| 1639 | |
---|
| 1640 | <p>The <b>Foo_linkopts</b> conventional macro will be automatically |
---|
| 1641 | inserted within the <b>use_linkopts</b> macro. And the shared |
---|
| 1642 | library location will be automatically set to the installation |
---|
| 1643 | areas.</p> |
---|
| 1644 | |
---|
| 1645 | <p>It is also possible to select extra tag sets when running |
---|
| 1646 | gmake as follows (in this example we first cleanup the previous |
---|
| 1647 | build and rebuild with debug options added to the compiler and |
---|
| 1648 | linker commands) :</p> |
---|
| 1649 | |
---|
| 1650 | <cmt:code> |
---|
| 1651 | > [g]make cleanup |
---|
| 1652 | > [g]make CMTEXTRATAGS=debug |
---|
| 1653 | </cmt:code> |
---|
| 1654 | |
---|
| 1655 | <p> Like all other make macros used to build a component, the |
---|
| 1656 | <b>Foo_linkopts</b> will be specified within the |
---|
| 1657 | <b>&CMTrequirements;</b> which gives several benefits: </p> |
---|
| 1658 | |
---|
| 1659 | <ul> |
---|
| 1660 | |
---|
| 1661 | <li> variants of the macro definition can be provided </li> |
---|
| 1662 | |
---|
| 1663 | <li> monitoring features of <b>CMT</b> such as the <b>cmt show |
---|
| 1664 | macro Foo_linkopts</b> command can be used later on </li> |
---|
| 1665 | |
---|
| 1666 | <li> macros defined this way may be later on inherited by |
---|
| 1667 | client packages which will <i>use</i> our package. </li> |
---|
| 1668 | |
---|
| 1669 | </ul> |
---|
| 1670 | |
---|
| 1671 | </cmt:section> |
---|
| 1672 | |
---|
| 1673 | <cmt:section title="Working on a test or external application"> |
---|
| 1674 | |
---|
| 1675 | It is also possible to work on a <i>test</i> or <i>external</i> |
---|
| 1676 | application, ie. when one does not wish to configure the |
---|
| 1677 | development for this application using <b>CMT</b>. Even in this |
---|
| 1678 | case, it is possible to benefit from the packages configured |
---|
| 1679 | using <b>CMT</b> by partially using <b>CMT</b>, just for |
---|
| 1680 | <i>used</i> relationships. |
---|
| 1681 | |
---|
| 1682 | <p> Here, no special convention is assumed on the location of |
---|
| 1683 | the sources, the binaries, the management scripts, |
---|
| 1684 | etc... However, it is possible to describe in a <b> |
---|
| 1685 | &CMTrequirements;</b> file the <i>use</i> relationships, as well |
---|
| 1686 | as the <b>make</b> macro definitions, quite similarly to the |
---|
| 1687 | package entirely configured using <b>CMT</b>. </p> |
---|
| 1688 | |
---|
| 1689 | <p> Most of the options provided by the <b>cmt</b> user |
---|
| 1690 | interface are still available in these conditions. </p> |
---|
| 1691 | |
---|
| 1692 | </cmt:section> |
---|
| 1693 | |
---|
| 1694 | <cmt:section title="Construction of a global environment"> |
---|
| 1695 | |
---|
| 1696 | <p>A software base generally consists in many <i>packages</i>, |
---|
| 1697 | some of them providing <i>libraries</i> or <i>documents</i>, |
---|
| 1698 | others providing <i>applications</i>, some providing both, some |
---|
| 1699 | providing just <i>glues</i> towards external software |
---|
| 1700 | products.</p> |
---|
| 1701 | |
---|
| 1702 | <p> On another view, this software base may a mix of packages |
---|
| 1703 | shared between several projects and sets of packages specific to |
---|
| 1704 | various projects. One may have several software bases as well |
---|
| 1705 | (combined using the <b>CMTPATH</b> environment variable). </p> |
---|
| 1706 | |
---|
| 1707 | <p> In such contexts, it is often desirable that a given project |
---|
| 1708 | defines its own selection of all existing packages. This can |
---|
| 1709 | easily be done with <b>CMT</b> by defining a <i>project</i> |
---|
| 1710 | package, containing only <b>use</b> statements towards the |
---|
| 1711 | appropriate selection of packages for this particular |
---|
| 1712 | project. </p> |
---|
| 1713 | |
---|
| 1714 | <p>Let's consider as an example the project named |
---|
| 1715 | <b>MyProject</b>. We may create the package named |
---|
| 1716 | <b>MyProject</b> similarly to any other package : </p> |
---|
| 1717 | |
---|
| 1718 | <cmt:code> |
---|
| 1719 | csh> cd ..... |
---|
| 1720 | csh> cmt create MyProject v1 /ProjectB |
---|
| 1721 | </cmt:code> |
---|
| 1722 | |
---|
| 1723 | <p> Then the <b> &CMTrequirements;</b> file of this new package |
---|
| 1724 | will simply contain a set of <b>use</b> statements, defining the |
---|
| 1725 | <i>official</i> set of validated versions of the packages |
---|
| 1726 | required for the project. This mechanism also represents the |
---|
| 1727 | notion of <i>global release</i> traditionally addressed in |
---|
| 1728 | configuration management environments </p> |
---|
| 1729 | |
---|
| 1730 | <cmt:code> |
---|
| 1731 | package MyProject |
---|
| 1732 | |
---|
| 1733 | use Cm v7r6 |
---|
| 1734 | use Db v4r3 |
---|
| 1735 | use El v4r2 |
---|
| 1736 | use Su v5 |
---|
| 1737 | use DbUI v1r2 Db |
---|
| 1738 | use ElUI v1r1 El |
---|
| 1739 | use VSUUI v3 Su/VSU |
---|
| 1740 | use VMM v1 |
---|
| 1741 | use VPC v3 |
---|
| 1742 | </cmt:code> |
---|
| 1743 | |
---|
| 1744 | <p>Then any user wanting to access the so-called <i>official</i> |
---|
| 1745 | release of the package set appropriate to the project |
---|
| 1746 | <b>MyProject</b> will simply do (typically within its login |
---|
| 1747 | shell script) : </p> |
---|
| 1748 | |
---|
| 1749 | <cmt:code> |
---|
| 1750 | # a login script |
---|
| 1751 | |
---|
| 1752 | ... |
---|
| 1753 | |
---|
| 1754 | source /ProjectB/MyProject/v1/cmt/setup.csh |
---|
| 1755 | </cmt:code> |
---|
| 1756 | |
---|
| 1757 | <p>Later on, future evolutions of the <b>MyProject</b> package |
---|
| 1758 | will reflect progressive integration steps, which |
---|
| 1759 | <i>validate</i> the evolutions of each referenced package. </p> |
---|
| 1760 | |
---|
| 1761 | </cmt:section> |
---|
| 1762 | |
---|
| 1763 | </cmt:section> |
---|
| 1764 | |
---|
| 1765 | <cmt:section title="Defining a document generator"> |
---|
| 1766 | |
---|
| 1767 | <p> In a Unix environment, documents are built using <b>make</b> |
---|
| 1768 | (well generally its <i>gnu</i> flavour) or <b>nmake</b> in Windows |
---|
| 1769 | environments. The basic mechanism provided in <b>CMT</b> relies on |
---|
| 1770 | <i>make fragment patterns</i> containing instructions on how to |
---|
| 1771 | rebuild document pieces. Many such generators are provided by |
---|
| 1772 | <b>CMT</b> itself so as to take care of of the most usual cases |
---|
| 1773 | (e.g. compilations, link operations, archive manipulations, |
---|
| 1774 | etc...). In addition to those, any package has to possibility to |
---|
| 1775 | provide a new generator for its own purpose, i.e. either for |
---|
| 1776 | providing rules for a special kind of document, or even to |
---|
| 1777 | override the default ones provided by <b>CMT</b>. This mechanism |
---|
| 1778 | is very similar to the definition or re-definition of |
---|
| 1779 | <i>macros</i> or environment variables in that every new generator |
---|
| 1780 | has to be first declared in a <b> &CMTrequirements;</b> file |
---|
| 1781 | belonging to a package (<b>CMT</b> actually declares all its |
---|
| 1782 | default generators within its <b>&CMTrequirements;</b> file), |
---|
| 1783 | allowing all its client packages to transparently acquire the |
---|
| 1784 | capacity to generate documents of that sort. </p> |
---|
| 1785 | |
---|
| 1786 | <p> <b>CMT</b> manages two categories of constituents: |
---|
| 1787 | |
---|
| 1788 | <ol> |
---|
| 1789 | |
---|
| 1790 | <li><i>Applications</i> and <i>Libraries</i> are handled using |
---|
| 1791 | pre-defined make fragments (mainly related with languages) and |
---|
| 1792 | behaviour. </li> |
---|
| 1793 | |
---|
| 1794 | <li><i>Documents</i> offer a quite general framework for |
---|
| 1795 | introducing completely new behaviours through user-defined |
---|
| 1796 | make fragments. This includes actually generating documents, |
---|
| 1797 | but also simply performing an operation (in which case |
---|
| 1798 | sometimes no real <i>document</i> is produced). </li> |
---|
| 1799 | |
---|
| 1800 | </ol> |
---|
| 1801 | </p> |
---|
| 1802 | |
---|
| 1803 | <p> In this section we only discuss the latter category and the |
---|
| 1804 | following paragraphs explain the framework used for defining new |
---|
| 1805 | document types. </p> |
---|
| 1806 | |
---|
| 1807 | <p>The main concept of this framework is that each document to be |
---|
| 1808 | generated or manipulated must be associated with a "document-type" |
---|
| 1809 | (also sometimes named "document-style"), which corresponds to a |
---|
| 1810 | dedicated make fragment of that name. Then, when specified in a |
---|
| 1811 | <b>document</b> statement, this make fragment will be |
---|
| 1812 | <i>instanciated</i> once or several times (typically once per |
---|
| 1813 | source file) to construct a complete and functional make fragment, |
---|
| 1814 | containing one main target. Both the resulting make fragment and |
---|
| 1815 | the make target will have the name of the constituent.</p> |
---|
| 1816 | |
---|
| 1817 | <cmt:section title="An example : the tex document-style"> |
---|
| 1818 | |
---|
| 1819 | <p> |
---|
| 1820 | |
---|
| 1821 | <cmt:blockquote> <i>This section discusses one simple example (the |
---|
| 1822 | production of postscript from latex files) available in the |
---|
| 1823 | standard <b>CMT</b> distribution kit. </i> </cmt:blockquote> |
---|
| 1824 | |
---|
| 1825 | </p> |
---|
| 1826 | |
---|
| 1827 | <p>Converting a latex source file into a postcript output |
---|
| 1828 | implies to chain two text processors, with an intermediate dvi |
---|
| 1829 | format.</p> |
---|
| 1830 | |
---|
| 1831 | <p>The fragment described here exactly performs this sequence, |
---|
| 1832 | taking care of intermediate file deletion. The document style is |
---|
| 1833 | named "tex" (the associated fragment shown here and named "tex" |
---|
| 1834 | is actually provided by <b>CMT</b> itself, and can be looked at |
---|
| 1835 | in <b>${CMTROOT}/fragments/tex</b>.) :</p> |
---|
| 1836 | |
---|
| 1837 | <cmt:code> |
---|
| 1838 | ============ tex ===================================== |
---|
| 1839 | ${CONSTITUENT} :: ${FILEPATH}/${NAME}.ps |
---|
| 1840 | |
---|
| 1841 | ${FILEPATH}/${NAME}.dvi : ${FULLNAME} |
---|
| 1842 | cd ${doc}; latex ${FULLNAME} |
---|
| 1843 | |
---|
| 1844 | ${FILEPATH}/${NAME}.ps : ${FILEPATH}/${NAME}.dvi |
---|
| 1845 | cd ${doc}; dvips ${FILEPATH}/${NAME}.dvi |
---|
| 1846 | |
---|
| 1847 | ${CONSTITUENT}clean :: |
---|
| 1848 | cd $(doc); /bin/rm -f ${FILEPATH}/${NAME}.ps ${FILEPATH}/${NAME}.dvi |
---|
| 1849 | |
---|
| 1850 | ====================================================== |
---|
| 1851 | </cmt:code> |
---|
| 1852 | |
---|
| 1853 | <ul> |
---|
| 1854 | |
---|
| 1855 | <li> They are declared in the <b>CMT</b>'s <a HREF="#The |
---|
| 1856 | requirements file">requirements</a> file as follows : |
---|
| 1857 | |
---|
| 1858 | <cmt:code> |
---|
| 1859 | make_fragment tex -header=tex_header |
---|
| 1860 | </cmt:code> |
---|
| 1861 | |
---|
| 1862 | where: |
---|
| 1863 | |
---|
| 1864 | <ol> |
---|
| 1865 | |
---|
| 1866 | <p></p> |
---|
| 1867 | |
---|
| 1868 | <li> "tex" represents both the fragment name and the document style. </li> |
---|
| 1869 | |
---|
| 1870 | <p></p> |
---|
| 1871 | |
---|
| 1872 | <li>the <b>-header=tex_header</b> option indicates that |
---|
| 1873 | the generated makefile fragment will first include this |
---|
| 1874 | header (which is actually an empty file in this case)</li> |
---|
| 1875 | |
---|
| 1876 | <p></p> |
---|
| 1877 | |
---|
| 1878 | </ol> |
---|
| 1879 | |
---|
| 1880 | </li> |
---|
| 1881 | |
---|
| 1882 | <li> A user package willing to apply this behaviour will have |
---|
| 1883 | to include in its &CMTrequirements; file a statement similar |
---|
| 1884 | to the following: |
---|
| 1885 | |
---|
| 1886 | <cmt:code> |
---|
| 1887 | document tex MyDoc -s=../doc doc1.tex doc2.tex |
---|
| 1888 | </cmt:code> |
---|
| 1889 | |
---|
| 1890 | where: |
---|
| 1891 | |
---|
| 1892 | <ol> |
---|
| 1893 | |
---|
| 1894 | <li> The first parameter "tex" is the document-style </li> |
---|
| 1895 | |
---|
| 1896 | <li> The second parameter "MyDoc" is used for building the |
---|
| 1897 | constituent's makefile (under the name MyDoc.make) and for |
---|
| 1898 | providing the make target "MyDoc". </li> |
---|
| 1899 | |
---|
| 1900 | <li> The other parameters (doc1.tex and doc2.tex) are the |
---|
| 1901 | sources of the document. Explicit location is required |
---|
| 1902 | (since default is currently defined to be ../src) </li> |
---|
| 1903 | |
---|
| 1904 | <li> The constituent's makefile MyDoc.make is built as |
---|
| 1905 | follows : |
---|
| 1906 | |
---|
| 1907 | <ol> |
---|
| 1908 | |
---|
| 1909 | <li> Install a copy of the |
---|
| 1910 | <b>$CMTROOT/fragments/make_header</b> generic fragment |
---|
| 1911 | </li> |
---|
| 1912 | |
---|
| 1913 | <li> Install a copy of the <b>$CMTROOT/fragments/tex_header</b> fragment </li> |
---|
| 1914 | |
---|
| 1915 | <li> For each of the sources, install a copy of the fragment "tex"</li> |
---|
| 1916 | |
---|
| 1917 | <li> Install a copy of the <b>$CMTROOT/fragments/cleanup_header</b> fragment </li> |
---|
| 1918 | |
---|
| 1919 | </ol> |
---|
| 1920 | |
---|
| 1921 | </li> |
---|
| 1922 | |
---|
| 1923 | </ol> |
---|
| 1924 | |
---|
| 1925 | <p>The result for our example is: </p> |
---|
| 1926 | |
---|
| 1927 | <cmt:code> |
---|
| 1928 | =========== MyDoc.make =============================== |
---|
| 1929 | |
---|
| 1930 | #==================================== |
---|
| 1931 | # Document MyDoc |
---|
| 1932 | # |
---|
| 1933 | # Generated by |
---|
| 1934 | # |
---|
| 1935 | #==================================== |
---|
| 1936 | |
---|
| 1937 | help :: |
---|
| 1938 | @echo 'MyDoc' |
---|
| 1939 | |
---|
| 1940 | doc1_dependencies = ../doc/doc1.tex |
---|
| 1941 | doc2_dependencies = ../doc/doc2.tex |
---|
| 1942 | |
---|
| 1943 | MyDoc :: ../doc/doc1.ps |
---|
| 1944 | |
---|
| 1945 | ../doc/doc1.dvi : $(doc)doc1.tex |
---|
| 1946 | cd ${doc}; latex $(doc)doc1.tex |
---|
| 1947 | |
---|
| 1948 | ../doc/doc1.ps : ../doc/doc1.dvi |
---|
| 1949 | cd ${doc}; dvips ../doc/doc1.dvi |
---|
| 1950 | |
---|
| 1951 | MyDocclean :: |
---|
| 1952 | cd $(doc); /bin/rm -f ../doc/doc1.ps ../doc/doc1.dvi |
---|
| 1953 | |
---|
| 1954 | MyDoc :: ../doc/doc2.ps |
---|
| 1955 | |
---|
| 1956 | ../doc/doc2.dvi : $(doc)doc2.tex |
---|
| 1957 | cd ${doc}; latex $(doc)doc2.tex |
---|
| 1958 | |
---|
| 1959 | ../doc/doc2.ps : ../doc/doc2.dvi |
---|
| 1960 | cd ${doc}; dvips ../doc/doc2.dvi |
---|
| 1961 | |
---|
| 1962 | MyDocclean :: |
---|
| 1963 | cd $(doc); /bin/rm -f ../doc/doc2.ps ../doc/doc2.dvi |
---|
| 1964 | |
---|
| 1965 | clean :: MyDocclean |
---|
| 1966 | cd . |
---|
| 1967 | |
---|
| 1968 | MyDocclean :: |
---|
| 1969 | ====================================================== |
---|
| 1970 | </cmt:code> |
---|
| 1971 | </li> |
---|
| 1972 | </ul> |
---|
| 1973 | |
---|
| 1974 | </cmt:section> |
---|
| 1975 | |
---|
| 1976 | <cmt:section title="How to create and install a new document style"> |
---|
| 1977 | |
---|
| 1978 | <p><cmt:blockquote><i>This section presents the general framework |
---|
| 1979 | for designing a document generator.</i></cmt:blockquote></p> |
---|
| 1980 | |
---|
| 1981 | <ol> |
---|
| 1982 | |
---|
| 1983 | <li> Select a name for the document style. It should not clash |
---|
| 1984 | with existing ones (use the <b>cmt show fragments</b> for a |
---|
| 1985 | complete list of document types currently defined).</li> |
---|
| 1986 | |
---|
| 1987 | <p></p> |
---|
| 1988 | |
---|
| 1989 | <li> A fragment exactly named after the document style name |
---|
| 1990 | must be installed into a subdirectory named <b>fragments</b> |
---|
| 1991 | below the <b>cmt</b> branch of a given package (which becomes |
---|
| 1992 | the <i>provider</i> package).</li> |
---|
| 1993 | |
---|
| 1994 | <p></p> |
---|
| 1995 | |
---|
| 1996 | <li> Optionally, two other fragments may be installed into the |
---|
| 1997 | same subdirectory, one of them will be the <i>header</i> of |
---|
| 1998 | the generated complete fragment, the other will be its |
---|
| 1999 | <i>trailer</i></li> |
---|
| 2000 | |
---|
| 2001 | <p></p> |
---|
| 2002 | |
---|
| 2003 | <li> Those fragments <i>must</i> be declared in the |
---|
| 2004 | &CMTrequirements; file of the provider package as follows: |
---|
| 2005 | |
---|
| 2006 | <cmt:code> |
---|
| 2007 | make_fragment <fragment-name> [ options... ] |
---|
| 2008 | </cmt:code> |
---|
| 2009 | |
---|
| 2010 | where options may be : |
---|
| 2011 | |
---|
| 2012 | <p> |
---|
| 2013 | |
---|
| 2014 | <table BORDER='1' COLS='2'> |
---|
| 2015 | <tr> |
---|
| 2016 | <td WIDTH="150">-suffix=<suffix></td> |
---|
| 2017 | <td width="500">provide the suffix of the output files (without the dot)</td> |
---|
| 2018 | </tr> |
---|
| 2019 | <tr> |
---|
| 2020 | <td>-header=<header></td> |
---|
| 2021 | <td>provide another make fragment meant to be prepended to |
---|
| 2022 | the constituent's make fragment.</td> |
---|
| 2023 | </tr> |
---|
| 2024 | <tr> |
---|
| 2025 | <td>-trailer=<trailer></td> |
---|
| 2026 | <td>provide another make fragment meant to be |
---|
| 2027 | appended to the constituent's make fragment.</td> |
---|
| 2028 | </tr> |
---|
| 2029 | <tr> |
---|
| 2030 | <td>-dependencies</td> |
---|
| 2031 | <td>install the automatic generation of dependencies into the |
---|
| 2032 | constituent's make fragment</td> |
---|
| 2033 | </tr> |
---|
| 2034 | </table> |
---|
| 2035 | </p> |
---|
| 2036 | </li> |
---|
| 2037 | </ol> |
---|
| 2038 | |
---|
| 2039 | <p>Once a fragment is installed and declared, it may be used by |
---|
| 2040 | any <i>client</i> package (ie a package <i>using</i> the |
---|
| 2041 | provider), and queried upon using the command</p> |
---|
| 2042 | |
---|
| 2043 | <cmt:code> |
---|
| 2044 | > cmt show fragment <fragment name> |
---|
| 2045 | </cmt:code> |
---|
| 2046 | |
---|
| 2047 | <p>which will show where this fragment is defined (ie. in which |
---|
| 2048 | of the used packages).</p> |
---|
| 2049 | |
---|
| 2050 | <p>The <b>cmt show fragments</b> commands lists all declared |
---|
| 2051 | fragments. </p> |
---|
| 2052 | |
---|
| 2053 | <p>If a package re-defines an already declared make fragment, ie |
---|
| 2054 | it provides a new copy of the fragment (possibly with new copies |
---|
| 2055 | of the header and the trailer), and declares it inside its |
---|
| 2056 | requirements file, then this package becomes the new provider |
---|
| 2057 | for the document style.</p> |
---|
| 2058 | |
---|
| 2059 | <p>For building a fragment, one may use pre-defined generic |
---|
| 2060 | "templates" (which will be substituted when a fragment is copied |
---|
| 2061 | into the final constituent's makefile).</p> |
---|
| 2062 | |
---|
| 2063 | <p> |
---|
| 2064 | <center> |
---|
| 2065 | <table BORDER='1' COLS='2'> |
---|
| 2066 | |
---|
| 2067 | <tr> |
---|
| 2068 | <td width="100">CONSTITUENT</td> |
---|
| 2069 | <td width="400">the constituent name</td> |
---|
| 2070 | </tr> |
---|
| 2071 | <tr> |
---|
| 2072 | <td>CONSTITUENTSUFFIX</td> |
---|
| 2073 | <td>the optional constituent's output suffix</td> |
---|
| 2074 | </tr> |
---|
| 2075 | <tr> |
---|
| 2076 | <td>FULLNAME</td> |
---|
| 2077 | <td>the full source path name (including directory and suffix)</td> |
---|
| 2078 | </tr> |
---|
| 2079 | <tr> |
---|
| 2080 | <td>FILENAME</td> |
---|
| 2081 | <td>the complete source file name (only including the suffix)</td> |
---|
| 2082 | </tr> |
---|
| 2083 | <tr> |
---|
| 2084 | <td>NAME</td> |
---|
| 2085 | <td>the short source file name (without directory and suffix)</td> |
---|
| 2086 | </tr> |
---|
| 2087 | <tr> |
---|
| 2088 | <td>FILEPATH</td> |
---|
| 2089 | <td>the source directory</td> |
---|
| 2090 | </tr> |
---|
| 2091 | |
---|
| 2092 | <tr> |
---|
| 2093 | <td>SUFFIX</td> |
---|
| 2094 | <td>the suffix provided in the -suffix option</td> |
---|
| 2095 | </tr> |
---|
| 2096 | |
---|
| 2097 | <tr> |
---|
| 2098 | <td>OBJS</td> |
---|
| 2099 | <td>(only available in headers) the list of |
---|
| 2100 | outputs, formed by a set of expressions : |
---|
| 2101 | |
---|
| 2102 | <cmt:code> |
---|
| 2103 | $(${CONSTITUENT}_output)${NAME}${SUFFIX} |
---|
| 2104 | </cmt:code> |
---|
| 2105 | |
---|
| 2106 | </td> |
---|
| 2107 | </tr> |
---|
| 2108 | |
---|
| 2109 | </table> |
---|
| 2110 | </center> |
---|
| 2111 | </p> |
---|
| 2112 | |
---|
| 2113 | <p>Templates must be enclosed between ${ and } or between $( and |
---|
| 2114 | ) and will be substituted at the generation time. Thus, if a |
---|
| 2115 | fragment contains the following text : </p> |
---|
| 2116 | |
---|
| 2117 | <cmt:code> |
---|
| 2118 | $(${CONSTITUENT}_output)${NAME}${SUFFIX} |
---|
| 2119 | </cmt:code> |
---|
| 2120 | |
---|
| 2121 | <p>then, the expanded constituent's makefile will contain |
---|
| 2122 | (refering to the "tex" example)</p> |
---|
| 2123 | |
---|
| 2124 | <cmt:code> |
---|
| 2125 | $(MyDoc_output)doc1.ps |
---|
| 2126 | </cmt:code> |
---|
| 2127 | |
---|
| 2128 | <p>Which shows that make macros may be dynamically generated. </p> |
---|
| 2129 | |
---|
| 2130 | <cmt:image src="Images/DocumentGenerator.jpg" |
---|
| 2131 | caption="The architecture of document generation."/> |
---|
| 2132 | |
---|
| 2133 | </cmt:section> |
---|
| 2134 | |
---|
| 2135 | <cmt:section title="Examples"> |
---|
| 2136 | |
---|
| 2137 | <ol> |
---|
| 2138 | |
---|
| 2139 | <li> rootcint |
---|
| 2140 | |
---|
| 2141 | <p>It generates C++ hubs for the Cint interpreter in Root. </p> |
---|
| 2142 | |
---|
| 2143 | <cmt:code> |
---|
| 2144 | ========= rootcint ========================================= |
---|
| 2145 | $(src)${NAME}.cc :: ${FULLNAME} |
---|
| 2146 | ${rootcint} -f $(src)${NAME}.cc -c ${FULLNAME} |
---|
| 2147 | ============================================================ |
---|
| 2148 | </cmt:code> |
---|
| 2149 | </li> |
---|
| 2150 | |
---|
| 2151 | <li> agetocxx and agetocxx_header. |
---|
| 2152 | |
---|
| 2153 | <p>It generates C++ source files (xxx.g files) from Atlas' AGE |
---|
| 2154 | description files. </p> |
---|
| 2155 | |
---|
| 2156 | <cmt:code> |
---|
| 2157 | ========= agetocxx ========================================= |
---|
| 2158 | output=$(${CONSTITUENT}_output) |
---|
| 2159 | |
---|
| 2160 | $(output)${NAME}.cxx : $(${NAME}_cxx_dependencies) |
---|
| 2161 | (echo '#line 1 "${FULLNAME}"'; cat ${FULLNAME}) > /tmp/${NAME}.gh.c |
---|
| 2162 | gcc -E -I$(output) $(use_includes) -D_GNU_SOURCE \ |
---|
| 2163 | cd ${output}; $(agetocxx) -o ${NAME} -ohd ${FILEPATH} \ |
---|
| 2164 | -ohp ${FILEPATH} /tmp/${NAME}.gh |
---|
| 2165 | rm -f /tmp/${NAME}.gh /tmp/${NAME}.gh.c |
---|
| 2166 | cd $(bin); $(cppcomp) $(use_cppflags) $(${CONSTITUENT}_cppflags) \ |
---|
| 2167 | $(${NAME}_cppflags) ${ADDINCLUDE} $(output)${NAME}.cxx |
---|
| 2168 | cd $(bin); $(ar) $(${CONSTITUENT}lib) ${NAME}.o; /bin/rm -f ${NAME}.o |
---|
| 2169 | ============================================================ |
---|
| 2170 | </cmt:code> |
---|
| 2171 | |
---|
| 2172 | <cmt:code> |
---|
| 2173 | ========= agetocxx_header ================================== |
---|
| 2174 | ${CONSTITUENT}lib = $(bin)lib${CONSTITUENT}.a |
---|
| 2175 | ${CONSTITUENT}stamp = $(bin)${CONSTITUENT}.stamp |
---|
| 2176 | ${CONSTITUENT}shstamp = $(bin)${CONSTITUENT}.shstamp |
---|
| 2177 | |
---|
| 2178 | ${CONSTITUENT} :: dirs ${CONSTITUENT}LIB |
---|
| 2179 | @/bin/echo ${CONSTITUENT} ok |
---|
| 2180 | |
---|
| 2181 | ${CONSTITUENT}LIB :: $(${CONSTITUENT}lib) $(${CONSTITUENT}shstamp) |
---|
| 2182 | @/bin/echo ${CONSTITUENT} : library ok |
---|
| 2183 | |
---|
| 2184 | $(${CONSTITUENT}lib) $(${CONSTITUENT}stamp) :: ${OBJS} |
---|
| 2185 | $(ranlib) $(${CONSTITUENT}lib) |
---|
| 2186 | cat /dev/null >$(${CONSTITUENT}stamp) |
---|
| 2187 | |
---|
| 2188 | $(${CONSTITUENT}shstamp) :: $(${CONSTITUENT}stamp) |
---|
| 2189 | cd $(bin); $(make_shlib) $(tag) ${CONSTITUENT} \ |
---|
| 2190 | $(${CONSTITUENT}shlibflags); \ |
---|
| 2191 | cat /dev/null >$(${CONSTITUENT}shstamp) |
---|
| 2192 | |
---|
| 2193 | ============================================================ |
---|
| 2194 | </cmt:code> |
---|
| 2195 | |
---|
| 2196 | It must be declared as follows : |
---|
| 2197 | |
---|
| 2198 | <cmt:code> |
---|
| 2199 | make_fragment agetocxx -suffix=cxx -dependencies -header=agetocxx_header |
---|
| 2200 | </cmt:code> |
---|
| 2201 | |
---|
| 2202 | </li> |
---|
| 2203 | </ol> |
---|
| 2204 | |
---|
| 2205 | </cmt:section> |
---|
| 2206 | |
---|
| 2207 | </cmt:section> |
---|
| 2208 | |
---|
| 2209 | <cmt:section title="The tools provided by CMT"> |
---|
| 2210 | |
---|
| 2211 | |
---|
| 2212 | The set of conventions and tools provided by <b>CMT</b> is |
---|
| 2213 | mainly composed of : |
---|
| 2214 | |
---|
| 2215 | <ul> |
---|
| 2216 | <li> |
---|
| 2217 | the syntax of the <b>&CMTrequirements;</b> file, |
---|
| 2218 | </li> |
---|
| 2219 | <li> |
---|
| 2220 | and the general <b>cmt</b> user interface, available in |
---|
| 2221 | the <b>mgr</b> branch of the <b>CMT</b> package. |
---|
| 2222 | </li> |
---|
| 2223 | </ul> |
---|
| 2224 | |
---|
| 2225 | The <i>setup</i> script found in the <b>CMT</b> installation |
---|
| 2226 | directory actually adds its location to the definition of the |
---|
| 2227 | standard <b>UNIX</b> <b>PATH</b> environment variable in order to |
---|
| 2228 | give direct access to the main <b>cmt</b> user interface. |
---|
| 2229 | |
---|
| 2230 | <p> |
---|
| 2231 | The sections below will detail the complete syntax of the |
---|
| 2232 | <b>&CMTrequirements;</b> file since it is the basis of most |
---|
| 2233 | information required to run the tools as well as the main |
---|
| 2234 | commands available through the <b>cmt</b> user interface. </p> |
---|
| 2235 | |
---|
| 2236 | <cmt:section title="The requirements file"> |
---|
| 2237 | |
---|
| 2238 | <cmt:section title="The general requirements syntax"> |
---|
| 2239 | |
---|
| 2240 | <ul> |
---|
| 2241 | <li> |
---|
| 2242 | A requirements file is made of <i>statements</i>, each describing |
---|
| 2243 | one named configuration parameter. |
---|
| 2244 | |
---|
| 2245 | <p>Statements generally occupy one single line, but may be |
---|
| 2246 | split into several lines using the reverse-slash character |
---|
| 2247 | (in this case the reverse-slash character <i>must</i> be |
---|
| 2248 | the last character on the line or must be only followed |
---|
| 2249 | by space characters).</p> |
---|
| 2250 | |
---|
| 2251 | <p>Each statement is composed of words separated with spaces |
---|
| 2252 | or tabulations.</p> |
---|
| 2253 | |
---|
| 2254 | <p>The first word of a statement is the name of the |
---|
| 2255 | configuration parameter.</p> |
---|
| 2256 | |
---|
| 2257 | <p>The rest of the statement provides the value assigned |
---|
| 2258 | to the configuration parameter.</p> |
---|
| 2259 | |
---|
| 2260 | </li> |
---|
| 2261 | |
---|
| 2262 | <li> |
---|
| 2263 | <p>Words composing a statement are separated with space or |
---|
| 2264 | tab characters. They may also be enclosed in quotes when |
---|
| 2265 | they have to include space or tab characters. Single or |
---|
| 2266 | double quotes may be freely used, as long as the same type |
---|
| 2267 | of quote is used on both sides of the word.</p> |
---|
| 2268 | |
---|
| 2269 | <p>Special characters (tabs, carriage-return and |
---|
| 2270 | line-feed) may be inserted into the statements using an |
---|
| 2271 | XML-based convention:</p> |
---|
| 2272 | |
---|
| 2273 | <center> |
---|
| 2274 | <table cols='2'> |
---|
| 2275 | |
---|
| 2276 | <tr> |
---|
| 2277 | <td> |
---|
| 2278 | <b>tabulation</b> |
---|
| 2279 | </td> |
---|
| 2280 | <td> |
---|
| 2281 | <b><tt><cmt:tab/></tt></b> |
---|
| 2282 | </td> |
---|
| 2283 | </tr> |
---|
| 2284 | |
---|
| 2285 | <tr> |
---|
| 2286 | <td> |
---|
| 2287 | <b>carriage-return</b> |
---|
| 2288 | </td> |
---|
| 2289 | <td> |
---|
| 2290 | <b><tt><cmt:cr/></tt></b> |
---|
| 2291 | </td> |
---|
| 2292 | </tr> |
---|
| 2293 | |
---|
| 2294 | <tr> |
---|
| 2295 | <td> |
---|
| 2296 | <b>line-feed</b> |
---|
| 2297 | </td> |
---|
| 2298 | <td> |
---|
| 2299 | <b><tt><cmt:lf/></tt></b> |
---|
| 2300 | </td> |
---|
| 2301 | </tr> |
---|
| 2302 | |
---|
| 2303 | </table> |
---|
| 2304 | </center> |
---|
| 2305 | <p></p> |
---|
| 2306 | </li> |
---|
| 2307 | |
---|
| 2308 | <li> |
---|
| 2309 | <p>Comments : they start with the <b>#</b> character and |
---|
| 2310 | extend up to the end of the current line. |
---|
| 2311 | </p> |
---|
| 2312 | </li> |
---|
| 2313 | |
---|
| 2314 | </ul> |
---|
| 2315 | |
---|
| 2316 | The complete syntax specification is available in <a href="#The complete requirements syntax">Appendix</a>. |
---|
| 2317 | |
---|
| 2318 | </cmt:section> |
---|
| 2319 | |
---|
| 2320 | </cmt:section> |
---|
| 2321 | |
---|
| 2322 | <cmt:section title="The concepts handled in the requirements file"> |
---|
| 2323 | |
---|
| 2324 | <cmt:section title="The package structuring style "> |
---|
| 2325 | |
---|
| 2326 | </cmt:section> |
---|
| 2327 | |
---|
| 2328 | <cmt:section title="Meta-information : author, manager"> |
---|
| 2329 | |
---|
| 2330 | The author and manager names |
---|
| 2331 | |
---|
| 2332 | </cmt:section> |
---|
| 2333 | |
---|
| 2334 | <cmt:section title="package, version"> |
---|
| 2335 | |
---|
| 2336 | The package name and version. These statements are purely |
---|
| 2337 | informational. |
---|
| 2338 | |
---|
| 2339 | </cmt:section> |
---|
| 2340 | |
---|
| 2341 | <cmt:section title="Constituents : application, library, document"> |
---|
| 2342 | |
---|
| 2343 | <p>Describe the composition of a constituent. Application |
---|
| 2344 | and library correspond to the standard meaning of an |
---|
| 2345 | application (an executable) and a library, while document |
---|
| 2346 | provides for a quite generic and open mechanism for |
---|
| 2347 | describing any type of document that can be generated from |
---|
| 2348 | sources.</p> |
---|
| 2349 | |
---|
| 2350 | <p>Applications and libraries are assigned a name (which |
---|
| 2351 | will correspond to a generated make fragment, and a |
---|
| 2352 | dedicated make target).</p> |
---|
| 2353 | |
---|
| 2354 | <p>A document is first associated with a document type |
---|
| 2355 | (which must correspond to a previously declared make |
---|
| 2356 | fragment). The document name is then used to name a |
---|
| 2357 | dedicated make fragment and a make target.</p> |
---|
| 2358 | |
---|
| 2359 | <p>Various options can be used when declaring a |
---|
| 2360 | constituent:</p> |
---|
| 2361 | |
---|
| 2362 | <center> |
---|
| 2363 | <table border='1' cols='3'> |
---|
| 2364 | |
---|
| 2365 | <tr> |
---|
| 2366 | <td width="200"><center><i>option</i></center></td> |
---|
| 2367 | <td width="150"><center><i>validity</i></center></td> |
---|
| 2368 | <td width="300"><center><i>usage</i></center></td> |
---|
| 2369 | </tr> |
---|
| 2370 | |
---|
| 2371 | <tr> |
---|
| 2372 | <td>-windows</td> |
---|
| 2373 | <td>applications</td> |
---|
| 2374 | <td>When used in a Windows environment, generates a GUI-based application (rather than a console application) </td> |
---|
| 2375 | </tr> |
---|
| 2376 | |
---|
| 2377 | <tr> |
---|
| 2378 | <td>-no_share</td> |
---|
| 2379 | <td>libraries</td> |
---|
| 2380 | <td>do not generate the shared library</td> |
---|
| 2381 | </tr> |
---|
| 2382 | |
---|
| 2383 | <tr> |
---|
| 2384 | <td>-no_static</td> |
---|
| 2385 | <td>libraries</td> |
---|
| 2386 | <td>do not generate the static library (<i>not yet implemented</i>)</td> |
---|
| 2387 | </tr> |
---|
| 2388 | |
---|
| 2389 | <tr> |
---|
| 2390 | <td>-prototypes</td> |
---|
| 2391 | <td>applications, libraries</td> |
---|
| 2392 | <td>do generate the prototype header files</td> |
---|
| 2393 | </tr> |
---|
| 2394 | |
---|
| 2395 | <tr> |
---|
| 2396 | <td>-no_prototypes</td> |
---|
| 2397 | <td>applications, libraries</td> |
---|
| 2398 | <td>do not generate the prototype header files</td> |
---|
| 2399 | </tr> |
---|
| 2400 | |
---|
| 2401 | <tr> |
---|
| 2402 | <td>-check</td> |
---|
| 2403 | <td>applications</td> |
---|
| 2404 | <td>generate a check target meant to execute the rebuilt application</td> |
---|
| 2405 | </tr> |
---|
| 2406 | |
---|
| 2407 | <tr> |
---|
| 2408 | <td>-group=group-name</td> |
---|
| 2409 | <td>any</td> |
---|
| 2410 | <td>install the constituent within this group target</td> |
---|
| 2411 | </tr> |
---|
| 2412 | |
---|
| 2413 | <tr> |
---|
| 2414 | <td>-suffix=suffix</td> |
---|
| 2415 | <td>applications, libraries</td> |
---|
| 2416 | <td>provide a suffix to names of all object files generated for this constituent <a href="#suffix option"><b>(1)</b></a></td> |
---|
| 2417 | </tr> |
---|
| 2418 | |
---|
| 2419 | <tr> |
---|
| 2420 | <td>-import=package</td> |
---|
| 2421 | <td>applications, libraries</td> |
---|
| 2422 | <td>explicitly import for this constituent the standard macros from a package that has the <b>-no_auto_imports</b> option set</td> |
---|
| 2423 | </tr> |
---|
| 2424 | |
---|
| 2425 | <tr> |
---|
| 2426 | <td>variable-name=variable-value</td> |
---|
| 2427 | <td>any</td> |
---|
| 2428 | <td>define a variable and its value to be given to the make fragment <a href="#variable-name option"><b>(2)</b></a></td> |
---|
| 2429 | </tr> |
---|
| 2430 | |
---|
| 2431 | </table> |
---|
| 2432 | </center> |
---|
| 2433 | |
---|
| 2434 | <ol> |
---|
| 2435 | |
---|
| 2436 | <li><a name="suffix option"></a> |
---|
| 2437 | |
---|
| 2438 | <p>When several constituents need to share source |
---|
| 2439 | files, (a typical example is for building different |
---|
| 2440 | libraries from the same sources but with different |
---|
| 2441 | compiler options), it is possible to specify an |
---|
| 2442 | optional output suffix with the |
---|
| 2443 | <b>-suffix=<suffix></b> option. With this |
---|
| 2444 | option, every object file name will be automatically |
---|
| 2445 | suffixed by the character string |
---|
| 2446 | "<b><suffix></b>", avoiding name conflicts |
---|
| 2447 | between the different targets, as in the following |
---|
| 2448 | example:</p> |
---|
| 2449 | |
---|
| 2450 | <cmt:code> |
---|
| 2451 | |
---|
| 2452 | library AXt -suffix=Xt *.cxx |
---|
| 2453 | library AXaw -suffix=Xaw *.cxx |
---|
| 2454 | |
---|
| 2455 | </cmt:code> |
---|
| 2456 | |
---|
| 2457 | </li> |
---|
| 2458 | |
---|
| 2459 | <li><a name="variable-name option"></a> |
---|
| 2460 | |
---|
| 2461 | <p>It's possible to specify in the list of parameters |
---|
| 2462 | one or more pairs of |
---|
| 2463 | <b>variable-name</b>=<b>variable-value</b> (without |
---|
| 2464 | any space characters around the <tt><b>"="</b></tt> |
---|
| 2465 | character), such as in the next example:</p> |
---|
| 2466 | |
---|
| 2467 | <cmt:code> |
---|
| 2468 | make_fragment doc_to_html (1) |
---|
| 2469 | |
---|
| 2470 | document doc_to_html Foo output=FooA.html FooA.doc (2) (3) |
---|
| 2471 | </cmt:code> |
---|
| 2472 | |
---|
| 2473 | |
---|
| 2474 | <ol> |
---|
| 2475 | |
---|
| 2476 | <li>This makefile fragment is meant to contain some text |
---|
| 2477 | conversion actions and defines a <a href="#Defining a |
---|
| 2478 | document generator"> document type</a> named |
---|
| 2479 | <b>doc_to_html</b>.</li> |
---|
| 2480 | |
---|
| 2481 | <li>This constituent exploits the document type |
---|
| 2482 | <b>doc_to_html</b> to convert the source <b>FooA.doc</b> |
---|
| 2483 | into an html file.</li> |
---|
| 2484 | |
---|
| 2485 | <li>The user defined template variable named <b>output</b> |
---|
| 2486 | is specified and assigned the value <b>FooA.html</b>. If the |
---|
| 2487 | fragment <b>doc_to_html</b> contains the string |
---|
| 2488 | <b>${output}</b>, then it will be substituted to |
---|
| 2489 | this value.</li> |
---|
| 2490 | |
---|
| 2491 | </ol> |
---|
| 2492 | |
---|
| 2493 | </li> |
---|
| 2494 | |
---|
| 2495 | </ol> |
---|
| 2496 | |
---|
| 2497 | </cmt:section> |
---|
| 2498 | |
---|
| 2499 | <cmt:section title="Groups"> |
---|
| 2500 | |
---|
| 2501 | Groups permit the organization of the constituents that must |
---|
| 2502 | be consistently built at the same development phases or with similar |
---|
| 2503 | constraints. |
---|
| 2504 | |
---|
| 2505 | <p>Each group is associated with a make target (of the same |
---|
| 2506 | name) which, when used in the make command, selectively |
---|
| 2507 | rebuilds all constituents of this group.</p> |
---|
| 2508 | |
---|
| 2509 | <p>The default group (into which all constituents are |
---|
| 2510 | installed by default) is named <b>all</b>, therefore, |
---|
| 2511 | running make without argument, activates the default target |
---|
| 2512 | (ie. <b>all</b>).</p> |
---|
| 2513 | |
---|
| 2514 | <p>As a typical usage of this mechanism, one may examplify the |
---|
| 2515 | case in which one or several constituents are making use of |
---|
| 2516 | one special facility (such as a database service, real-time |
---|
| 2517 | features, graphical libraries) and therefore might require a |
---|
| 2518 | controled re-build. This is especially useful for having these |
---|
| 2519 | constituents only rebuilt on demand rather than rebuilt |
---|
| 2520 | automatically when the default make command is run.</p> |
---|
| 2521 | |
---|
| 2522 | <p>One could, for instance specify within the requirements file :</p> |
---|
| 2523 | |
---|
| 2524 | <cmt:code> |
---|
| 2525 | # Constituents belonging to the default <i>all</i> group |
---|
| 2526 | |
---|
| 2527 | <i>... constituents without group specification ...</i> |
---|
| 2528 | |
---|
| 2529 | # Constituents belonging to specific groups |
---|
| 2530 | |
---|
| 2531 | library Foo-objy -group=objy <<i>sources making use of Objectivity</i>> |
---|
| 2532 | |
---|
| 2533 | application FooGUI -group=graphics <<i>sources making use of Qt</i>> |
---|
| 2534 | application BarGUI -group=graphics <<i>sources making use of Qt</i>> |
---|
| 2535 | |
---|
| 2536 | </cmt:code> |
---|
| 2537 | |
---|
| 2538 | <i>(Beware of the position of the -group option which must be |
---|
| 2539 | located after the constituent name. Any other position will be |
---|
| 2540 | misunderstood by CMT)</i> |
---|
| 2541 | |
---|
| 2542 | <p>Then, running <b>gmake all</b> would only rebuild the un-grouped |
---|
| 2543 | constituents, whereas running</p> |
---|
| 2544 | |
---|
| 2545 | <cmt:code> |
---|
| 2546 | > gmake objy |
---|
| 2547 | > gmake graphics |
---|
| 2548 | </cmt:code> |
---|
| 2549 | |
---|
| 2550 | <p>in the context of the <b>Foo</b> package would rebuild <i>objy</i> |
---|
| 2551 | related or <i>graphics</i> related constituents.</p> |
---|
| 2552 | |
---|
| 2553 | </cmt:section> |
---|
| 2554 | |
---|
| 2555 | <cmt:section title="Languages"> |
---|
| 2556 | |
---|
| 2557 | Some computer languages are known by default by <b>CMT</b> |
---|
| 2558 | (<b>C</b>, <b>C</b>++, <b>Fortran77</b>, <b>Java</b>, |
---|
| 2559 | <b>lex</b>, <b>yacc</b>). However it is possible to extend |
---|
| 2560 | this knowledge to any other langage. |
---|
| 2561 | |
---|
| 2562 | <p>We consider here languages that are able to produce object |
---|
| 2563 | files from sources.</p> |
---|
| 2564 | |
---|
| 2565 | <p>Let's take an example. We would like to install support for |
---|
| 2566 | Fortran90. We first have to <i>declare</i> this new language |
---|
| 2567 | support to <b>CMT</b> within the <b>requirements</b> file of |
---|
| 2568 | one of our packages (Notice that it's not at all required to |
---|
| 2569 | modify <b>CMT</b> itself since all clients of the selected |
---|
| 2570 | package will inherit the knowledge of this language).</p> |
---|
| 2571 | |
---|
| 2572 | <p>The language support is simply named <b>fortran90</b> and is |
---|
| 2573 | declared by the following statement:</p> |
---|
| 2574 | |
---|
| 2575 | <cmt:code> |
---|
| 2576 | language fortran90 \ |
---|
| 2577 | -suffix=f90 -suffix=F90 \ [1] |
---|
| 2578 | -linker=$(f90link) \ [2] |
---|
| 2579 | -preprocessor_command=$(ppcmd) |
---|
| 2580 | </cmt:code> |
---|
| 2581 | |
---|
| 2582 | <ol> |
---|
| 2583 | |
---|
| 2584 | <li>The recognized suffixes for source files will be <b>f90</b> and <b>F90</b></li> |
---|
| 2585 | |
---|
| 2586 | <li>The linker command used to build a Fortran90 application |
---|
| 2587 | is described inside the macro named <b>f90link</b> (which |
---|
| 2588 | must defined in this requirements file but which can also be |
---|
| 2589 | overridden by clients)</li> |
---|
| 2590 | |
---|
| 2591 | </ol> |
---|
| 2592 | |
---|
| 2593 | <p>The language support being named <b>fortran90</b>, two |
---|
| 2594 | associated make fragments are expected, one under the name |
---|
| 2595 | <b>fortran90</b> (for building application modules), the |
---|
| 2596 | other with the name <b>fortran90_library</b> (for modules |
---|
| 2597 | meant to be archived), both without extension.</p> |
---|
| 2598 | |
---|
| 2599 | <p>These two fragments should be installed in the |
---|
| 2600 | <b>fragments</b> sub-directory of the cmt branch of our |
---|
| 2601 | package.</p> |
---|
| 2602 | |
---|
| 2603 | <p>Due to the similarity of the example to fortran77, we |
---|
| 2604 | may easily provide the expected fragments simply by |
---|
| 2605 | copying the f77 fragments found in <b>CMT</b> (thus the |
---|
| 2606 | fragments <b>${CMTROOT}/fragments/fortran</b> and |
---|
| 2607 | <b>${CMTROOT}/fragments/fortran_library</b></p> |
---|
| 2608 | |
---|
| 2609 | <p>These fragments make use of the <b>fcomp</b> macro, |
---|
| 2610 | which holds the fortran77 compiler command (through the |
---|
| 2611 | <b>for</b> macro).</p> |
---|
| 2612 | |
---|
| 2613 | <cmt:code> |
---|
| 2614 | macro for "f77" \ |
---|
| 2615 | ... |
---|
| 2616 | macro fcomp "$(for) -c $(fincludes) $(fflags) $(pp_fflags)" |
---|
| 2617 | </cmt:code> |
---|
| 2618 | |
---|
| 2619 | <p>We therefore simply replace these macros by new macros |
---|
| 2620 | named <b>f90comp</b> and <b>f90</b>, defined as |
---|
| 2621 | follows:</p> |
---|
| 2622 | |
---|
| 2623 | <cmt:code> |
---|
| 2624 | macro f90 "f90" |
---|
| 2625 | ... |
---|
| 2626 | macro f90comp "$(f90) -c $(fincludes) $(fflags) $(pp_fflags)" |
---|
| 2627 | </cmt:code> |
---|
| 2628 | |
---|
| 2629 | <p>Some languages (this has been seen for example in the |
---|
| 2630 | IDL generators in Corba environments) do provide several |
---|
| 2631 | object files from one unique source file. It is possible |
---|
| 2632 | to specify this feature through the (repetitive) |
---|
| 2633 | <b>-extra_output_suffix</b> option like in:</p> |
---|
| 2634 | |
---|
| 2635 | <cmt:code> |
---|
| 2636 | language idl -suffix=idl -fragment=idl -extra_output_suffix=_skel |
---|
| 2637 | </cmt:code> |
---|
| 2638 | |
---|
| 2639 | where, in this case, two object files are produced for each |
---|
| 2640 | IDL source file, one named <b><<i>name</i>>.o</b> the |
---|
| 2641 | other named <b><<i>name</i>>_skel.o</b>. |
---|
| 2642 | |
---|
| 2643 | </cmt:section> |
---|
| 2644 | |
---|
| 2645 | <cmt:section title="Symbols"> |
---|
| 2646 | |
---|
| 2647 | <p>The <b>alias</b> keyword is translated into a shell alias |
---|
| 2648 | definition, </p> |
---|
| 2649 | |
---|
| 2650 | <p>The <b>set</b> keyword is translated into an environment |
---|
| 2651 | variable definition.</p> |
---|
| 2652 | |
---|
| 2653 | <p>The <b>macro</b> keyword is translated into a |
---|
| 2654 | <b>make</b>'s macro definition.</p> |
---|
| 2655 | |
---|
| 2656 | <p>The <b>path</b> keyword is translated into a |
---|
| 2657 | <i>path</i>-like environment variable, which is supposed to |
---|
| 2658 | be composed of search paths separated with colon characters |
---|
| 2659 | <b>':'</b> (on Unix) or semi-colon characters <b>';'</b> (on |
---|
| 2660 | Windows). However, it is highly recommended to construct such |
---|
| 2661 | a |
---|
| 2662 | variable by iteratively concatenating individual items one by |
---|
| 2663 | one using <i>path_append</i> or <i>path_prepend</i></p> |
---|
| 2664 | |
---|
| 2665 | <p>Variants of these keywords are also provided for |
---|
| 2666 | modifying already defined symbols. This generally happens |
---|
| 2667 | when a package needs to modify an inherited symbol |
---|
| 2668 | (ie. which has been already defined by a used |
---|
| 2669 | package). Through the keywords <b>set_append</b>, |
---|
| 2670 | <b>set_prepend</b>, <b>set_remove</b>, <b>macro_append</b>, |
---|
| 2671 | <b>macro_prepend</b>, <b>macro_remove</b>, |
---|
| 2672 | <b>macro_remove_all</b>, <b>path_append</b>, |
---|
| 2673 | <b>path_prepend</b>, <b>path_remove</b> one can append or |
---|
| 2674 | prepend a text to the existing symbol value or remove a part |
---|
| 2675 | from it. The <b>path_remove</b> keyword removes all |
---|
| 2676 | individual search paths that <i>contain</i> the specified |
---|
| 2677 | sub-string.</p> |
---|
| 2678 | |
---|
| 2679 | <p>The translations occur while running either the setup |
---|
| 2680 | scripts (for alias, set or path) or the make command (for |
---|
| 2681 | macro).</p> |
---|
| 2682 | |
---|
| 2683 | <p>All these definitions follow the same pattern:</p> |
---|
| 2684 | |
---|
| 2685 | <cmt:syntax name="symbol"> |
---|
| 2686 | <cmt:rule name="symbol"> |
---|
| 2687 | <cmt:alt> |
---|
| 2688 | <cmt:term name="symbol-type"/> |
---|
| 2689 | <cmt:term name="symbol-name"/> |
---|
| 2690 | <cmt:term name="default-value"/> |
---|
| 2691 | <cmt:optionseq> |
---|
| 2692 | <cmt:term name="tag"/> |
---|
| 2693 | <cmt:term name="value"/> |
---|
| 2694 | </cmt:optionseq> |
---|
| 2695 | </cmt:alt> |
---|
| 2696 | </cmt:rule> |
---|
| 2697 | </cmt:syntax> |
---|
| 2698 | |
---|
| 2699 | <p></p> |
---|
| 2700 | |
---|
| 2701 | The symbol-name identifies the symbol for modification |
---|
| 2702 | operations. The default-value is optionally followed by a set |
---|
| 2703 | of tag/value pairs, each representing an alternate value for |
---|
| 2704 | this symbol. Be aware that there is only one name space for |
---|
| 2705 | all kinds of symbols. Therefore, if a symbol was originally |
---|
| 2706 | defined using a <b>macro</b> statement, using |
---|
| 2707 | <b>set_append</b> to modify it will produce an undefined |
---|
| 2708 | result. |
---|
| 2709 | |
---|
| 2710 | <p>The tag is used to select one alternate value to replace |
---|
| 2711 | the default value, when one of the following condition is met:</p> |
---|
| 2712 | |
---|
| 2713 | <ul> |
---|
| 2714 | |
---|
| 2715 | <li>It matches the value of the CMTSITE environment variable |
---|
| 2716 | (or registry)</li> |
---|
| 2717 | |
---|
| 2718 | <li>It matches the value provided by the uname Unix command |
---|
| 2719 | (when available)</li> |
---|
| 2720 | |
---|
| 2721 | <li>It matches the value of the CMTCONFIG environment |
---|
| 2722 | variable (or registry)</li> |
---|
| 2723 | |
---|
| 2724 | <li>It matches the value specified in the |
---|
| 2725 | -tag=<i>tag</i> argument to the cmt command.</li> |
---|
| 2726 | |
---|
| 2727 | <li>It matches one user defined tag (see the tag keyword) |
---|
| 2728 | which itself is associated with a matching tag (Note that |
---|
| 2729 | this is a recursive definition).</li> |
---|
| 2730 | |
---|
| 2731 | </ul> |
---|
| 2732 | |
---|
| 2733 | <p>Examples of such definition are : </p> |
---|
| 2734 | |
---|
| 2735 | <cmt:code> |
---|
| 2736 | package CMT |
---|
| 2737 | |
---|
| 2738 | macro cflags "" \ |
---|
| 2739 | LynxOS-VGPW2 "-X" \ |
---|
| 2740 | insure "-std1" \ |
---|
| 2741 | HP-UX "+Z" \ |
---|
| 2742 | hp700_ux101 "-fpic -ansi" \ |
---|
| 2743 | alpha "-std1" \ |
---|
| 2744 | alphat "-std1" \ |
---|
| 2745 | SunOS "-KPIC" \ |
---|
| 2746 | WIN32 '/nologo /DWIN32 /MD /W3 $(includes) /c' |
---|
| 2747 | |
---|
| 2748 | macro pp_cflags "" \ |
---|
| 2749 | LynxOS-VGPW2 "-DVGPW2" \ |
---|
| 2750 | HP-UX "-D_HPUX_SOURCE" \ |
---|
| 2751 | alphat "-DCTHREADS" \ |
---|
| 2752 | AIX "-D_ALL_SOURCE -D_BSD" \ |
---|
| 2753 | Linux "-Di586" |
---|
| 2754 | |
---|
| 2755 | macro ccomp "$(cc) -c $(includes) $(cdebugflags) $(cflags) $(pp_cflags)" \ |
---|
| 2756 | VisualC "cl.exe $(cdebugflags) $(cflags) $(pp_cflags)" |
---|
| 2757 | |
---|
| 2758 | macro clinkflags "" |
---|
| 2759 | |
---|
| 2760 | macro clink "$(cc) $(clinkflags)" \ |
---|
| 2761 | VisualC "link.exe /nologo /machine:IX86 " |
---|
| 2762 | |
---|
| 2763 | </cmt:code> |
---|
| 2764 | |
---|
| 2765 | </cmt:section> |
---|
| 2766 | |
---|
| 2767 | <cmt:section title="use"> |
---|
| 2768 | |
---|
| 2769 | <p>Describe the relationships with other packages; the |
---|
| 2770 | generic syntax is :</p> |
---|
| 2771 | |
---|
| 2772 | <cmt:code> |
---|
| 2773 | use <package> [ <version> [ <root> ] ] |
---|
| 2774 | </cmt:code> |
---|
| 2775 | |
---|
| 2776 | <p>Omitting the version specification means that the most |
---|
| 2777 | recent version (ie. the one with highest ids) that can be |
---|
| 2778 | found from the search path list will be automatically |
---|
| 2779 | selected.</p> |
---|
| 2780 | |
---|
| 2781 | <p> The root specification can be relative (ie. on Unix it |
---|
| 2782 | does not contain a leading '/' character). In this case, |
---|
| 2783 | this prefix is systematically considered when the package |
---|
| 2784 | is looked for in the search path list. But it can also be |
---|
| 2785 | absolute (ie. with a leading '/' character on Unix), in |
---|
| 2786 | which case this path takes precedence over the standard |
---|
| 2787 | search path list (see CMTPATH).</p> |
---|
| 2788 | |
---|
| 2789 | <p> Examples of such relationships are :</p> |
---|
| 2790 | |
---|
| 2791 | <cmt:code> |
---|
| 2792 | # Packages installed in the default root : |
---|
| 2793 | use OnX v5r2 |
---|
| 2794 | use CSet v2r3 |
---|
| 2795 | use Gb v2r1 |
---|
| 2796 | |
---|
| 2797 | # A package installed in a root one step below the root : |
---|
| 2798 | use CS v3r1 virgo |
---|
| 2799 | |
---|
| 2800 | # Back to the default root : |
---|
| 2801 | use Cm v7r3 |
---|
| 2802 | |
---|
| 2803 | # Get the most recent version of CERNLIB |
---|
| 2804 | use CERNLIB |
---|
| 2805 | </cmt:code> |
---|
| 2806 | |
---|
| 2807 | <p>By default, a set of standard macros, which are |
---|
| 2808 | expected to be specified by used packages, is |
---|
| 2809 | automatically imported from them (see the <A |
---|
| 2810 | HREF="#Package customizing macros">detailed list</A> of |
---|
| 2811 | these macros). This automatic feature can be discarded |
---|
| 2812 | using the <br/><b>-no_auto_imports</b> option to the use |
---|
| 2813 | statement, or re-activated using the |
---|
| 2814 | <br/><b>-auto_imports</b>. When it is discarded, the |
---|
| 2815 | macros will not be transparently inherited, but rather, |
---|
| 2816 | each individual constituent willing to make use of them |
---|
| 2817 | will have to explicitly import them using the |
---|
| 2818 | <b>-import=<<i>package</i>></b> <a |
---|
| 2819 | href="#constituents">option</a>.</p> |
---|
| 2820 | |
---|
| 2821 | <p>When a <b>use</b> statement is in a <b>private</b> |
---|
| 2822 | section, the corresponding used package will only be |
---|
| 2823 | reached if when <b>CMT</b> operations occur in the context |
---|
| 2824 | of the holder package. Otherwise (ie if the operation |
---|
| 2825 | occurs in some upper level client package, then this |
---|
| 2826 | <i>privately</i> used package will be entirely |
---|
| 2827 | hidden. (<i>This behaviour follows a very similar pattern |
---|
| 2828 | to the private or public inheritance of C++</i>). Suppose |
---|
| 2829 | we have the following organization:</p> |
---|
| 2830 | |
---|
| 2831 | <cmt:code> |
---|
| 2832 | ---------------- |
---|
| 2833 | package A |
---|
| 2834 | |
---|
| 2835 | use B v1 |
---|
| 2836 | use D v1 |
---|
| 2837 | ---------------- |
---|
| 2838 | |
---|
| 2839 | ---------------- |
---|
| 2840 | package B |
---|
| 2841 | |
---|
| 2842 | private |
---|
| 2843 | use C v1 |
---|
| 2844 | use D v1 |
---|
| 2845 | ---------------- |
---|
| 2846 | |
---|
| 2847 | </cmt:code> |
---|
| 2848 | |
---|
| 2849 | <ul> |
---|
| 2850 | <li> all operations done in the context of package B will <i>see</i> both packages C and D</li> |
---|
| 2851 | <li> all operations done in the context of package A will <i>see</i> both packages B and D, but not package C</li> |
---|
| 2852 | </ul> |
---|
| 2853 | |
---|
| 2854 | </cmt:section> |
---|
| 2855 | |
---|
| 2856 | <cmt:section title="patterns"> |
---|
| 2857 | |
---|
| 2858 | <p>Often, similar configuration items are needed over a |
---|
| 2859 | set of packages (sometimes over all packages of a |
---|
| 2860 | project). This reflects either similarities between |
---|
| 2861 | packages or generic conventions established by a project |
---|
| 2862 | or a team.</p> |
---|
| 2863 | |
---|
| 2864 | <p>Typical examples are the definition of the search path |
---|
| 2865 | for shared libraries (through the <b>LD_LIBRARY_PATH</b> |
---|
| 2866 | environment variable), the systematic production of test |
---|
| 2867 | applications, etc.</p> |
---|
| 2868 | |
---|
| 2869 | <p>The concept of pattern proposed here implements this |
---|
| 2870 | genericity. Patterns may be either <i>global</i>, in which |
---|
| 2871 | case they will be systematically applied onto every |
---|
| 2872 | package, or <i>local</i> (the default) in which case they |
---|
| 2873 | will be applied on demand only by each package.</p> |
---|
| 2874 | |
---|
| 2875 | <p>The general principle of a pattern is to associate a |
---|
| 2876 | templated (set of) <b>cmt</b> statement(s) with the |
---|
| 2877 | pattern name. Then every time the pattern is applied, its |
---|
| 2878 | associated statements are applied as if they were directly |
---|
| 2879 | specified in the requirements file, replacing the template |
---|
| 2880 | with its current value. If several statements are to be |
---|
| 2881 | associated with a given pattern, they will be separated |
---|
| 2882 | with the <b>" ; "</b> separator pattern (beware of really |
---|
| 2883 | enclosing the ";" between two space characters).</p> |
---|
| 2884 | |
---|
| 2885 | <p>The general syntax for defining a pattern in a |
---|
| 2886 | requirements file is:</p> |
---|
| 2887 | |
---|
| 2888 | <cmt:syntax name="pattern"> |
---|
| 2889 | <cmt:rule name="pattern"> |
---|
| 2890 | <cmt:alt> |
---|
| 2891 | <cmt:kwd/> |
---|
| 2892 | <cmt:option><cmt:kwd name="-global"/></cmt:option> |
---|
| 2893 | <cmt:term name="pattern-name"/> |
---|
| 2894 | <cmt:ruleref name="cmt-statement"/> |
---|
| 2895 | </cmt:alt> |
---|
| 2896 | <cmt:continuation> |
---|
| 2897 | <cmt:optionseq> |
---|
| 2898 | <cmt:kwd name=" ; "/> |
---|
| 2899 | <cmt:ruleref name="cmt-statement"/> |
---|
| 2900 | </cmt:optionseq> |
---|
| 2901 | </cmt:continuation> |
---|
| 2902 | </cmt:rule> |
---|
| 2903 | </cmt:syntax> |
---|
| 2904 | |
---|
| 2905 | <p>Pattern templates are names enclosed between the '<' |
---|
| 2906 | and '>' characters. A set of predefined templates are |
---|
| 2907 | automatically provided by <b>CMT</b>:</p> |
---|
| 2908 | |
---|
| 2909 | <p> |
---|
| 2910 | <center> |
---|
| 2911 | <table BORDER='1' COLS='2'> |
---|
| 2912 | <tr> |
---|
| 2913 | <td width="80"><b>package</b></td> |
---|
| 2914 | <td width="300">the name of the current package</td> |
---|
| 2915 | </tr> |
---|
| 2916 | <tr> |
---|
| 2917 | <td><b>PACKAGE</b></td> |
---|
| 2918 | <td>the name of the current package in upper case</td> |
---|
| 2919 | </tr> |
---|
| 2920 | <tr> |
---|
| 2921 | <td><b>version</b></td> |
---|
| 2922 | <td>the version tag of the current package</td> |
---|
| 2923 | </tr> |
---|
| 2924 | <tr> |
---|
| 2925 | <td><b>path</b></td> |
---|
| 2926 | <td>the access path of the current package</td> |
---|
| 2927 | </tr> |
---|
| 2928 | </table> |
---|
| 2929 | </center> |
---|
| 2930 | </p> |
---|
| 2931 | |
---|
| 2932 | <p>Then, in addition, user defined templates can be installed |
---|
| 2933 | within the pattern definitions. Their actual value will be |
---|
| 2934 | provided as arguments to the apply_pattern statement.</p> |
---|
| 2935 | |
---|
| 2936 | <p>User defined templates that have not been assigned a value |
---|
| 2937 | when the pattern is applied are simply ignored.</p> |
---|
| 2938 | |
---|
| 2939 | <p>Some examples:</p> |
---|
| 2940 | |
---|
| 2941 | <ol> |
---|
| 2942 | <li> |
---|
| 2943 | <p>Changing the standard include search path.</p> |
---|
| 2944 | |
---|
| 2945 | <p>The standard include path is set by default to |
---|
| 2946 | <b>${<package>_root}/src</b>. However, often projects |
---|
| 2947 | need to override this default convention, and typical |
---|
| 2948 | example is to set it to a branch named with the package |
---|
| 2949 | name. This convention is easily applied by defining a |
---|
| 2950 | pattern which will apply the include_path statement as |
---|
| 2951 | follows:</p> |
---|
| 2952 | |
---|
| 2953 | <cmt:code> |
---|
| 2954 | pattern -global include_path include_path ${<package>_root}/<package>/ |
---|
| 2955 | </cmt:code> |
---|
| 2956 | |
---|
| 2957 | <p>For instance, a package named <b>PackA</b> will expand this |
---|
| 2958 | pattern as follows:</p> |
---|
| 2959 | |
---|
| 2960 | <cmt:code> |
---|
| 2961 | include_path ${PackA_root}/PackA/ |
---|
| 2962 | </cmt:code> |
---|
| 2963 | </li> |
---|
| 2964 | <li> |
---|
| 2965 | <p>Providing a value to the <b>LD_LIBRARY_PATH</b> environment variable</p> |
---|
| 2966 | |
---|
| 2967 | <p>On some operating systems (eg. Linux), shared library |
---|
| 2968 | paths must be explicited, through an environment |
---|
| 2969 | variable. The following pattern can automate this operation:</p> |
---|
| 2970 | |
---|
| 2971 | <cmt:code> |
---|
| 2972 | pattern ld_library_path \ |
---|
| 2973 | path_remove LD_LIBRARY_PATH "/<package>/" ; \ |
---|
| 2974 | path_append LD_LIBRARY_PATH ${<PACKAGE>ROOT}/${CMTCONFIG} |
---|
| 2975 | </cmt:code> |
---|
| 2976 | |
---|
| 2977 | <p>In this example, the pattern was not set global, so |
---|
| 2978 | that only packages actually providing shared libraries |
---|
| 2979 | would be concerned. These packages will simply have to |
---|
| 2980 | apply the pattern as follows:</p> |
---|
| 2981 | |
---|
| 2982 | <cmt:code> |
---|
| 2983 | apply_pattern ld_library_path |
---|
| 2984 | </cmt:code> |
---|
| 2985 | |
---|
| 2986 | <p>The schema installed by this pattern provides first a |
---|
| 2987 | cleanup of the <b>LD_LIBRARY_PATH</b> environment variable |
---|
| 2988 | and then the new assignment. This choice is useful in this |
---|
| 2989 | case to avoid conflicting definitions from two different |
---|
| 2990 | versions of the same package.</p> |
---|
| 2991 | |
---|
| 2992 | </li> |
---|
| 2993 | |
---|
| 2994 | <li> |
---|
| 2995 | <p>Installing a systematic test application in all packages</p> |
---|
| 2996 | |
---|
| 2997 | <p>Quality assurance requirements might specify that every |
---|
| 2998 | package should provide a test program. One way to enforce |
---|
| 2999 | this is to build a global pattern declaring this |
---|
| 3000 | application. Then every make command would naturally |
---|
| 3001 | ensure its actual presence.</p> |
---|
| 3002 | |
---|
| 3003 | <cmt:code> |
---|
| 3004 | pattern quality_test application <package>test <package>test.cxx <other_sources> |
---|
| 3005 | </cmt:code> |
---|
| 3006 | |
---|
| 3007 | <p>In this example, an additional pattern |
---|
| 3008 | (<other_sources>) permits the package to specify |
---|
| 3009 | extra source files to the test application (the pattern |
---|
| 3010 | assumes at least one source file <package>test.cxx).</p> |
---|
| 3011 | |
---|
| 3012 | </li> |
---|
| 3013 | </ol> |
---|
| 3014 | |
---|
| 3015 | </cmt:section> |
---|
| 3016 | |
---|
| 3017 | <cmt:section title="cmtpath_patterns"> |
---|
| 3018 | |
---|
| 3019 | <p>Those patterns act quite similarly to the patterns |
---|
| 3020 | previously described, ie they defines a set of CMT |
---|
| 3021 | statements to be applied in a generic way.</p> |
---|
| 3022 | |
---|
| 3023 | <p>The only varying parameter that can be specified here |
---|
| 3024 | is the token <path> which stands for any entry in |
---|
| 3025 | the CMTPATH list.</p> |
---|
| 3026 | |
---|
| 3027 | <p>Therefore whenever a cmtpath_pattern is defined and if |
---|
| 3028 | it specifies the expression <path> in its |
---|
| 3029 | definition, then an implicit loop over all entries of the |
---|
| 3030 | CMTPATH list will be run and one instance of the pattern |
---|
| 3031 | will be applied for each entry in the CMTPATH list.</p> |
---|
| 3032 | |
---|
| 3033 | <p>As an example suppose we define</p> |
---|
| 3034 | |
---|
| 3035 | <cmt:code> |
---|
| 3036 | path CMTPATH "/ProjectA" |
---|
| 3037 | path_append CMTPATH "/ProjectB" |
---|
| 3038 | |
---|
| 3039 | cmtpath_pattern \ |
---|
| 3040 | macro_prepend pp_cppflags " -I<path>/InstallArea/include " |
---|
| 3041 | </cmt:code> |
---|
| 3042 | |
---|
| 3043 | <p>this will assemble one -I option (towards the |
---|
| 3044 | preprocessor) per entry in CMTPATH, implementing a |
---|
| 3045 | mechanism for a multiple installation area for header |
---|
| 3046 | files. In the example above the resulting macro will |
---|
| 3047 | be</p> |
---|
| 3048 | |
---|
| 3049 | <cmt:code> |
---|
| 3050 | -I/ProjectA/InstallArea/include -I/ProjectB/InstallArea/include |
---|
| 3051 | </cmt:code> |
---|
| 3052 | |
---|
| 3053 | <p> |
---|
| 3054 | This can be combined with the standard and |
---|
| 3055 | <a href="#Generated macros">automatic macros</a> |
---|
| 3056 | (automatically setup for all used packages) |
---|
| 3057 | |
---|
| 3058 | <cmt:code> |
---|
| 3059 | <package>_cmtpath |
---|
| 3060 | <package>_offset |
---|
| 3061 | </cmt:code> |
---|
| 3062 | |
---|
| 3063 | which provide the CMTPATH entry and the directory offset |
---|
| 3064 | in this CMTPATH for all used packages. |
---|
| 3065 | |
---|
| 3066 | </p> |
---|
| 3067 | |
---|
| 3068 | </cmt:section> |
---|
| 3069 | |
---|
| 3070 | <cmt:section title="branches"> |
---|
| 3071 | |
---|
| 3072 | <p>Describe the specific directory branches to be added while |
---|
| 3073 | configuring the package.</p> |
---|
| 3074 | |
---|
| 3075 | <cmt:code> |
---|
| 3076 | branches <branch-name> ... |
---|
| 3077 | </cmt:code> |
---|
| 3078 | |
---|
| 3079 | <p> These branches will be created (if needed) at the same |
---|
| 3080 | level as the <b>cmt</b> branch. Typical examples of such |
---|
| 3081 | required branches may be <b>include</b>, <b>test</b> or |
---|
| 3082 | <b>data</b>.</p> |
---|
| 3083 | |
---|
| 3084 | </cmt:section> |
---|
| 3085 | |
---|
| 3086 | <cmt:section title="Strategy specifications"> |
---|
| 3087 | |
---|
| 3088 | <p>Users can control the behaviour of <b>CMT</b> through a |
---|
| 3089 | set of strategy specifications. The current implementation |
---|
| 3090 | provides such control over several aspects :</p> |
---|
| 3091 | |
---|
| 3092 | <ol> |
---|
| 3093 | |
---|
| 3094 | <li> |
---|
| 3095 | |
---|
| 3096 | <p>The build strategy</p> |
---|
| 3097 | |
---|
| 3098 | <p>This controls and parameterized the building |
---|
| 3099 | process the way makefile fragments used for |
---|
| 3100 | applications and libraries. </p> |
---|
| 3101 | |
---|
| 3102 | <p>The following keywords are available:</p> |
---|
| 3103 | |
---|
| 3104 | <p> |
---|
| 3105 | <center> |
---|
| 3106 | <table BORDER='1' COLS='2'> |
---|
| 3107 | <tr> |
---|
| 3108 | <td width="80"><b>prototypes</b></td> |
---|
| 3109 | |
---|
| 3110 | <td width="500">C source files will |
---|
| 3111 | automatically produce a header file containing |
---|
| 3112 | a prototype of all global entry points</td> |
---|
| 3113 | |
---|
| 3114 | </tr> |
---|
| 3115 | |
---|
| 3116 | <tr> |
---|
| 3117 | <td width="80"><b>no_prototypes</b></td> |
---|
| 3118 | |
---|
| 3119 | <td width="500">No production of automatic |
---|
| 3120 | prototype header files for C sources</td> |
---|
| 3121 | |
---|
| 3122 | </tr> |
---|
| 3123 | |
---|
| 3124 | <tr> |
---|
| 3125 | <td width="80"><b>with_install_area</b></td> |
---|
| 3126 | |
---|
| 3127 | <td width="500">The installation area |
---|
| 3128 | mechanisms are activated. This implies |
---|
| 3129 | applying the cmtpath_patterns that may be |
---|
| 3130 | defined (eg in CMT itself)</td> |
---|
| 3131 | |
---|
| 3132 | </tr> |
---|
| 3133 | |
---|
| 3134 | <tr> |
---|
| 3135 | <td width="80"><b>without_install_area</b></td> |
---|
| 3136 | |
---|
| 3137 | <td width="500">The installation area |
---|
| 3138 | mechanisms are inhibited</td> |
---|
| 3139 | |
---|
| 3140 | </tr> |
---|
| 3141 | |
---|
| 3142 | </table> |
---|
| 3143 | </center> |
---|
| 3144 | </p> |
---|
| 3145 | |
---|
| 3146 | </li> |
---|
| 3147 | |
---|
| 3148 | <li> |
---|
| 3149 | <p>The setup strategy</p> |
---|
| 3150 | |
---|
| 3151 | <p>This controls various actions that may be performed |
---|
| 3152 | during the sourcing of the setup scripts.</p> |
---|
| 3153 | |
---|
| 3154 | <p>The following keywords are available:</p> |
---|
| 3155 | |
---|
| 3156 | <p> |
---|
| 3157 | <center> |
---|
| 3158 | <table BORDER='1' COLS='2'> |
---|
| 3159 | |
---|
| 3160 | <tr> |
---|
| 3161 | <td width="80"><b>config</b></td> |
---|
| 3162 | |
---|
| 3163 | <td width="500">An environment variable |
---|
| 3164 | <PACKAGE>CONFIG will be generated for all |
---|
| 3165 | packages in the dependency chain</td> |
---|
| 3166 | |
---|
| 3167 | </tr> |
---|
| 3168 | |
---|
| 3169 | <tr> |
---|
| 3170 | <td width="80"><b>no_config</b></td> |
---|
| 3171 | |
---|
| 3172 | <td width="500">The <PACKAGE>CONFIG |
---|
| 3173 | environment variable is not generated </td> |
---|
| 3174 | |
---|
| 3175 | </tr> |
---|
| 3176 | |
---|
| 3177 | <tr> |
---|
| 3178 | <td width="80"><b>root</b></td> |
---|
| 3179 | |
---|
| 3180 | <td width="500">An environment variable |
---|
| 3181 | <PACKAGE>ROOT will be generated for all |
---|
| 3182 | packages in the dependency chain</td> |
---|
| 3183 | |
---|
| 3184 | </tr> |
---|
| 3185 | |
---|
| 3186 | <tr> |
---|
| 3187 | <td width="80"><b>no_root</b></td> |
---|
| 3188 | |
---|
| 3189 | <td width="500">The <PACKAGE>ROOT |
---|
| 3190 | environment variable is not generated </td> |
---|
| 3191 | |
---|
| 3192 | </tr> |
---|
| 3193 | |
---|
| 3194 | <tr> |
---|
| 3195 | <td width="80"><b>cleanup</b></td> |
---|
| 3196 | |
---|
| 3197 | <td width="500">The automatic cleanup |
---|
| 3198 | operation to the current installation |
---|
| 3199 | area is launched</td> |
---|
| 3200 | |
---|
| 3201 | </tr> |
---|
| 3202 | |
---|
| 3203 | <tr> |
---|
| 3204 | <td width="80"><b>no_cleanup</b></td> |
---|
| 3205 | |
---|
| 3206 | <td width="500">The automatic cleanup |
---|
| 3207 | operation to the current installation |
---|
| 3208 | area is not launched</td> |
---|
| 3209 | |
---|
| 3210 | </tr> |
---|
| 3211 | |
---|
| 3212 | </table> |
---|
| 3213 | </center> |
---|
| 3214 | </p> |
---|
| 3215 | |
---|
| 3216 | </li> |
---|
| 3217 | |
---|
| 3218 | </ol> |
---|
| 3219 | |
---|
| 3220 | </cmt:section> |
---|
| 3221 | <cmt:section title="setup_script, cleanup_script"> |
---|
| 3222 | |
---|
| 3223 | <p>Specify user defined configuration scripts, which will be |
---|
| 3224 | activated together with the execution of the main |
---|
| 3225 | <b>setup</b> and <b>cleanup</b> scripts.</p> |
---|
| 3226 | |
---|
| 3227 | <p> The script names may be specified without any access path |
---|
| 3228 | specification, in this case, they are looked for in the |
---|
| 3229 | <b>cmt</b> or <b>mgr</b> branch of the package |
---|
| 3230 | itself. They may also be specified without any <b>.csh</b> |
---|
| 3231 | or <b>.sh</b> suffix, the appropriate suffix will be |
---|
| 3232 | appended accordingly when needed. Therefore, when such a user |
---|
| 3233 | configuration script is specified, <b>CMT</b> expects that |
---|
| 3234 | the corresponding shell scripts actually exist in the |
---|
| 3235 | appropriate directory (the <b>cmt</b> branch by default) and |
---|
| 3236 | is provided in whatever format is appropriate (thus suffixed |
---|
| 3237 | by <b>.csh</b> and/or <b>.sh</b>).</p> |
---|
| 3238 | |
---|
| 3239 | </cmt:section> |
---|
| 3240 | |
---|
| 3241 | <cmt:section title="include_path"> |
---|
| 3242 | |
---|
| 3243 | <p>Override the specification for the default include search |
---|
| 3244 | path, which is internally set to |
---|
| 3245 | ${<<i>package</i>>_root}/src.</p> |
---|
| 3246 | |
---|
| 3247 | <p>Specifying the value <i>none</i> (a reserved CMT keyword) |
---|
| 3248 | means that no default include search path is expected from |
---|
| 3249 | CMT, and thus no -I compiler option will be generated by |
---|
| 3250 | default (generally this means that user include search paths |
---|
| 3251 | should be specified via <i>include_dirs</i> instead).</p> |
---|
| 3252 | |
---|
| 3253 | </cmt:section> |
---|
| 3254 | |
---|
| 3255 | <cmt:section title="include_dirs"> |
---|
| 3256 | |
---|
| 3257 | <p>Add specifications for non-standard include access paths.</p> |
---|
| 3258 | |
---|
| 3259 | </cmt:section> |
---|
| 3260 | |
---|
| 3261 | <cmt:section title="make_fragment"> |
---|
| 3262 | |
---|
| 3263 | <p>This statement specifies a specialized makefile fragment, |
---|
| 3264 | used as a building brick to construct the final makefile |
---|
| 3265 | fragment dedicated to build the constituents.</p> |
---|
| 3266 | |
---|
| 3267 | <p>There are basically three categories of such fragments : |
---|
| 3268 | <ol> |
---|
| 3269 | <li>some are provided by <b>CMT</b> itself (they |
---|
| 3270 | correspond to its internal behaviour)</li> |
---|
| 3271 | <li>others handle the language support</li> |
---|
| 3272 | <li>and the last serve as specialized document generators.</li> |
---|
| 3273 | </ol> |
---|
| 3274 | </p> |
---|
| 3275 | |
---|
| 3276 | <p>The fragments defined in <b>CMT</b> can be:</p> |
---|
| 3277 | |
---|
| 3278 | <ul> |
---|
| 3279 | |
---|
| 3280 | <li> those used to construct the application or library |
---|
| 3281 | constituents. Their semantic is |
---|
| 3282 | standardized (they are all associated with a |
---|
| 3283 | <b>language</b> statement in the CMT requirements |
---|
| 3284 | file). |
---|
| 3285 | |
---|
| 3286 | <cmt:blockquote> |
---|
| 3287 | <i> |
---|
| 3288 | c c_library cpp cpp_library lex lex_library fortran |
---|
| 3289 | fortran_library yacc yacc_library jar jar_header |
---|
| 3290 | java java_copy java_header check_java cleanup_java |
---|
| 3291 | </i> |
---|
| 3292 | </cmt:blockquote> |
---|
| 3293 | |
---|
| 3294 | </li> |
---|
| 3295 | |
---|
| 3296 | <li> those used internally by CMT as primary building |
---|
| 3297 | blocks for assembling the makefile. (Generally developers |
---|
| 3298 | should not see them). |
---|
| 3299 | |
---|
| 3300 | <cmt:blockquote> |
---|
| 3301 | <i> |
---|
| 3302 | cleanup_objects application |
---|
| 3303 | constituent application_header constituents_header |
---|
| 3304 | buildproto protos_header os9_header dependencies |
---|
| 3305 | check_application dependencies_and_triggers |
---|
| 3306 | check_application_header document_header library |
---|
| 3307 | cleanup library_header cleanup_application |
---|
| 3308 | library_no_share cleanup_header make_header |
---|
| 3309 | cleanup_library |
---|
| 3310 | </i> |
---|
| 3311 | </cmt:blockquote> |
---|
| 3312 | |
---|
| 3313 | </li> |
---|
| 3314 | |
---|
| 3315 | <li> some document generators which <i>may</i> be used if |
---|
| 3316 | needed, but are not mandatory: |
---|
| 3317 | <cmt:blockquote> |
---|
| 3318 | <i> |
---|
| 3319 | installer installer_header readme readme_header |
---|
| 3320 | readme_trailer readme_use dvi tex generator |
---|
| 3321 | generator_header |
---|
| 3322 | </i> |
---|
| 3323 | </cmt:blockquote> |
---|
| 3324 | |
---|
| 3325 | </li> |
---|
| 3326 | |
---|
| 3327 | <li> those used to generate configuration files for MSVisualC++: |
---|
| 3328 | <cmt:blockquote> |
---|
| 3329 | <i> |
---|
| 3330 | dsp_windows_header dsw_all_project |
---|
| 3331 | dsw_all_project_dependency dsw_all_project_header |
---|
| 3332 | dsw_all_project_trailer dsw_header dsw_project |
---|
| 3333 | dsw_trailer dsp_all dsp_application_header |
---|
| 3334 | dsp_contents dsp_library_header |
---|
| 3335 | dsp_shared_library_header dsp_trailer |
---|
| 3336 | </i> |
---|
| 3337 | </cmt:blockquote> |
---|
| 3338 | |
---|
| 3339 | </li> |
---|
| 3340 | |
---|
| 3341 | </ul> |
---|
| 3342 | |
---|
| 3343 | <p>Language fragments should provide two forms, one for the |
---|
| 3344 | applications (in which case they are named exactly after the |
---|
| 3345 | language name eg c, cpp, fortran) and the other for the |
---|
| 3346 | libraries (in which case they have the <b>_library</b> |
---|
| 3347 | suffix (eg. c_library, cpp_library, fortran_library). A set |
---|
| 3348 | of language definitions (C, C++, Fortran, Java, Lex, Yacc) |
---|
| 3349 | is provided by CMT itself but it is expected that projects |
---|
| 3350 | add new languages according to their needs. Event if the |
---|
| 3351 | make fragment meant to be the implementation of a language |
---|
| 3352 | support is declared, the language support itself must be |
---|
| 3353 | declared too, using the <b>language statement</b> </p> |
---|
| 3354 | |
---|
| 3355 | <p>All make fragments are provided as (suffixless) files |
---|
| 3356 | which must be located in the <b>fragments</b> |
---|
| 3357 | sub-directory inside the cmt/mgr branch of one |
---|
| 3358 | package. They must also be declared in the requirements |
---|
| 3359 | file (through the <b>make_fragment</b> statement) so as to |
---|
| 3360 | be visible.</p> |
---|
| 3361 | |
---|
| 3362 | <p>A package declaring, and implementing a make fragment may |
---|
| 3363 | override a fragment of the same name when it is already |
---|
| 3364 | declared by a used package. This implies in particular that |
---|
| 3365 | any package <b>may</b> freely override any make fragment |
---|
| 3366 | provided by <b>CMT</b> itself (although in this case a deep |
---|
| 3367 | understanding of what the original fragment does is |
---|
| 3368 | recommended).</p> |
---|
| 3369 | |
---|
| 3370 | <p>Makefile fragments may take any form convenient to the |
---|
| 3371 | document style, and some special pre-built templates (see |
---|
| 3372 | the <A HREF="#Standard templates for makefile |
---|
| 3373 | fragments">appendix</A>) can be used in their body to |
---|
| 3374 | represent running values, meant to be |
---|
| 3375 | properly expanded at actual generation time :</p> |
---|
| 3376 | |
---|
| 3377 | <p><table BORDER='1' COLS='2'> |
---|
| 3378 | <tr> |
---|
| 3379 | <td width="150"><b>CONSTITUENT</b></td> |
---|
| 3380 | <td width="300">the constituent name</td> |
---|
| 3381 | </tr> |
---|
| 3382 | <tr> |
---|
| 3383 | <td><b>FULLNAME</b></td> |
---|
| 3384 | <td>the full source path</td> |
---|
| 3385 | </tr> |
---|
| 3386 | <tr> |
---|
| 3387 | <td><b>FILENAME</b></td> |
---|
| 3388 | <td>the source file name without its path</td> |
---|
| 3389 | </tr> |
---|
| 3390 | <tr> |
---|
| 3391 | <td><b>NAME</b></td> |
---|
| 3392 | <td>the source file name without its path and suffix</td> |
---|
| 3393 | </tr> |
---|
| 3394 | <tr> |
---|
| 3395 | <td><b>FILESUFFIX</b></td> |
---|
| 3396 | <td>the dotted file suffix</td> |
---|
| 3397 | </tr> |
---|
| 3398 | <tr> |
---|
| 3399 | <td><b>FILEPATH</b></td> |
---|
| 3400 | <td>the output path</td> |
---|
| 3401 | </tr> |
---|
| 3402 | <tr> |
---|
| 3403 | <td><b>SUFFIX</b></td> |
---|
| 3404 | <td>the default suffix for output files</td> |
---|
| 3405 | </tr> |
---|
| 3406 | </table> |
---|
| 3407 | </p> |
---|
| 3408 | |
---|
| 3409 | </cmt:section> |
---|
| 3410 | |
---|
| 3411 | <cmt:section title="public, private"> |
---|
| 3412 | |
---|
| 3413 | <p>Introduce a section for <i>public</i> or <i>private</i> |
---|
| 3414 | statements. This only concerns the definition of symbols |
---|
| 3415 | or the specification of use relationships.</p> |
---|
| 3416 | |
---|
| 3417 | <p>Symbols are the environment variables or aliases in a |
---|
| 3418 | <b>Unix</b> environment or as <i>logical names</i> or |
---|
| 3419 | <i>symbols</i> in a <b>VMS</b> one). <i>Macros</i> to be |
---|
| 3420 | used within makefiles can also be defined at this |
---|
| 3421 | level. Public symbols are meant to be exported to any |
---|
| 3422 | external user of the package whereas private ones are only |
---|
| 3423 | defined for the package <i>developper</i>. Currently the |
---|
| 3424 | selection between these two categories is done when the |
---|
| 3425 | setup script is executed : if it is executed while |
---|
| 3426 | actually being in the <b>cmt</b> branch of the package, |
---|
| 3427 | the developper category is assumed. If the script is |
---|
| 3428 | executed from another directory the user category is |
---|
| 3429 | assumed.</p> |
---|
| 3430 | |
---|
| 3431 | <p>Public use relationships expose the complete sub-tree |
---|
| 3432 | to the package clients, whereas private ones entirely hide |
---|
| 3433 | the sub-tree, expanding it only when the operator really |
---|
| 3434 | acts from within the context of the package. It should be |
---|
| 3435 | noticed that private use relationships are completely |
---|
| 3436 | unvisible from clients, which implies that none of the |
---|
| 3437 | definitions (not only symbols) will be set.</p> |
---|
| 3438 | |
---|
| 3439 | <p>However, the cmt broadcast command is configured to |
---|
| 3440 | always ignore the private specification and will traverse |
---|
| 3441 | the sub-trees whether they are public or private (in order |
---|
| 3442 | to ensure the hierarchy dependencies)</p> |
---|
| 3443 | |
---|
| 3444 | </cmt:section> |
---|
| 3445 | |
---|
| 3446 | <cmt:section title="tag"> |
---|
| 3447 | |
---|
| 3448 | <p>Provide tag definitions.</p> |
---|
| 3449 | |
---|
| 3450 | <p> A tag is a token which can be used to select particular |
---|
| 3451 | values of symbols. Generally a tag need not being explicitly |
---|
| 3452 | declared, since the reference to it will declare the tag |
---|
| 3453 | automatically. However, tags may be used to <i>name</i> a |
---|
| 3454 | particular association of several other tags. In this case, |
---|
| 3455 | this association must be declared within a <a HREF="#The |
---|
| 3456 | requirements file">requirements</a> file as follows :</p> |
---|
| 3457 | |
---|
| 3458 | <cmt:code> |
---|
| 3459 | tag <association-tag-name> <tag1> <tag2> ... |
---|
| 3460 | |
---|
| 3461 | eg: |
---|
| 3462 | |
---|
| 3463 | tag Linux-gcc Linux gcc |
---|
| 3464 | |
---|
| 3465 | </cmt:code> |
---|
| 3466 | |
---|
| 3467 | <p>This definition implies that when <i>Linux-gcc</i> is |
---|
| 3468 | true, then both <i>Linux</i> and <i>gcc</i> are true.</p> |
---|
| 3469 | |
---|
| 3470 | <p>This can be exploited to trigger via only one tag, the |
---|
| 3471 | activation of several individual tags, each signing a |
---|
| 3472 | particular condition (in our example the <i>debug</i> |
---|
| 3473 | condition and the <i>Linux</i> environment).</p> |
---|
| 3474 | |
---|
| 3475 | <p>However, it is always possible to dynamically associate |
---|
| 3476 | several tags by using the <i>tag-list</i>-style of arguments |
---|
| 3477 | to the -tag=<tag-list> options to the cmt command |
---|
| 3478 | driver (such as in <i>cmt setup -tag=Linux,debug</i>) </p> |
---|
| 3479 | |
---|
| 3480 | <p>Tags or associations of tags are propagated using the |
---|
| 3481 | -tag=<tag-list> options to the cmt command driver, but |
---|
| 3482 | the Make command can also accept them through the |
---|
| 3483 | conventional macros <i>$(tag)</i> and |
---|
| 3484 | <i>$(extra_tags)</i>. However, the <i>$(tag)</i> macro |
---|
| 3485 | itself can only accept one value (instead of a list), and |
---|
| 3486 | therefore in order to give a list of additional tags, one |
---|
| 3487 | should use the <i>$(extra_tags)</i> (such as in <i>gmake |
---|
| 3488 | tag=Linux extra_tags=debug</i>) </p> |
---|
| 3489 | |
---|
| 3490 | <p>Finally, running the setup script (through the <i>source |
---|
| 3491 | setup.[c]sh</i> or <i>call setup.bat</i> command ) can also |
---|
| 3492 | receive tag specifications using the <i>-tag=tag-list</i> |
---|
| 3493 | options.</p> |
---|
| 3494 | |
---|
| 3495 | </cmt:section> |
---|
| 3496 | |
---|
| 3497 | </cmt:section> |
---|
| 3498 | |
---|
| 3499 | <cmt:section title="The general cmt user interface"> |
---|
| 3500 | |
---|
| 3501 | This utility (a shell script combined with a <b>C</b> |
---|
| 3502 | application) provides a centralised access to various commands |
---|
| 3503 | to the <b>CMT</b> system. The first way to use <b>cmt</b> is |
---|
| 3504 | to run it without argument, this will print a minimal help text |
---|
| 3505 | showing the basic commands and their syntax : |
---|
| 3506 | |
---|
| 3507 | <cmt:code> |
---|
| 3508 | > cmt command [option...] |
---|
| 3509 | command : |
---|
| 3510 | broadcast [-select=list] [-exclude=list] [-local] [-depth=n] |
---|
| 3511 | [-global] [-begin=pattern] |
---|
| 3512 | [-all_packages] <command> : apply a command to [some of] the used packages |
---|
| 3513 | build <key> : build various components : |
---|
| 3514 | constituent_makefile : generate Makefile |
---|
| 3515 | constituents_makefile : generate constituents.make |
---|
| 3516 | dependencies : generate dependencies |
---|
| 3517 | library_links : build symbolic links towards all imported libraries |
---|
| 3518 | msdev : generate MSDEV files |
---|
| 3519 | os9_makefile : generate Makefile for OS9 |
---|
| 3520 | prototype : generate prototype file |
---|
| 3521 | readme : generate README.html |
---|
| 3522 | tag_makefile : generate tag specific Makefile |
---|
| 3523 | |
---|
| 3524 | check <key> : perform various checks |
---|
| 3525 | configuration : check configuration |
---|
| 3526 | files <old> <new> : compare two files and overrides <old> by <new> if different |
---|
| 3527 | version <name> : check if a name follows a version tag syntax |
---|
| 3528 | check_files <old> <new> : compare two files and overrides <old> by <new> if different |
---|
| 3529 | checkout : perform a cvs checkout over a CMT package |
---|
| 3530 | co : perform a cvs checkout over a CMT package |
---|
| 3531 | cleanup [-csh|-sh|-bat] : generate a cleanup script |
---|
| 3532 | config : generate setup and cleanup scripts |
---|
| 3533 | create <package> <version> [<path>] : create and configure a new package |
---|
| 3534 | filter <in> <out> : filter a file against CMT macros and env. variables |
---|
| 3535 | help : display this help |
---|
| 3536 | lock : lock the current package |
---|
| 3537 | lock <package> <version> [<path>] : lock a package |
---|
| 3538 | remove <package> <version> [<path>] : remove a version of a package |
---|
| 3539 | remove library_links : remove symbolic links towards all imported libraries |
---|
| 3540 | run <command> : apply a command |
---|
| 3541 | setup [-csh|-sh|-bat] : generate a setup script |
---|
| 3542 | show <key> : display various infos on : |
---|
| 3543 | all_tags : all defined tags |
---|
| 3544 | applied_patterns : all applied patterns in this package |
---|
| 3545 | author : package author |
---|
| 3546 | branches : added branches |
---|
| 3547 | clients : package clients |
---|
| 3548 | constituent_names : constituent names |
---|
| 3549 | constituents : constituent definitions |
---|
| 3550 | cycles : cycles in the use graph |
---|
| 3551 | uses : the use tree |
---|
| 3552 | fragment <name> : one fragment definition |
---|
| 3553 | fragments : fragment definitions |
---|
| 3554 | groups : group definitions |
---|
| 3555 | languages : language definitions |
---|
| 3556 | macro <name> : a formatted macro definition |
---|
| 3557 | macro_value <name> : a raw macro definition |
---|
| 3558 | macros : all macro definitions |
---|
| 3559 | manager : package manager |
---|
| 3560 | packages : packages reachable from the current context |
---|
| 3561 | path : the package search list |
---|
| 3562 | pattern <name> : the pattern definition and usages |
---|
| 3563 | patterns : the pattern definitions |
---|
| 3564 | pwd : filtered current directory |
---|
| 3565 | set_value <name> : a raw set definition |
---|
| 3566 | set <name> : a formatted set definition |
---|
| 3567 | sets : set definitions |
---|
| 3568 | strategies : all strategies (build & version) |
---|
| 3569 | tags : all active tags |
---|
| 3570 | uses : used packages |
---|
| 3571 | use_paths <target> : all paths towards the target package |
---|
| 3572 | version : version of the current package |
---|
| 3573 | versions <name> : visible versions of the selected package |
---|
| 3574 | |
---|
| 3575 | system : display the system tag |
---|
| 3576 | unlock : unlock the current package |
---|
| 3577 | unlock <package> <version> [<path>] : unlock a package |
---|
| 3578 | version : version of CMT |
---|
| 3579 | |
---|
| 3580 | cvstags <module> : display the CVS tags for a module |
---|
| 3581 | cvsbranches <module> : display the subdirectories for a module |
---|
| 3582 | cvssubpackagess <module> : display the subpackages for a module |
---|
| 3583 | |
---|
| 3584 | global option : |
---|
| 3585 | -quiet : don't print errors |
---|
| 3586 | -use=<p>:<v>:<path> : set package version path |
---|
| 3587 | -pack=<package> : set package |
---|
| 3588 | -version=<version> : set version |
---|
| 3589 | -path=<path> : set root path |
---|
| 3590 | -f=<requirement-file> : set input file |
---|
| 3591 | -e=<statement> : add a one line statement |
---|
| 3592 | -home=<directory> : find a home requirements file there |
---|
| 3593 | -tag=<tag-list> : select specific tag(s) |
---|
| 3594 | -private : force navigation through private uses |
---|
| 3595 | -public : inhibit navigation through private uses (the default) |
---|
| 3596 | </cmt:code> |
---|
| 3597 | |
---|
| 3598 | <p>The following sections present the detail of each available command. </p> |
---|
| 3599 | |
---|
| 3600 | <cmt:section title="cmt broadcast"> |
---|
| 3601 | |
---|
| 3602 | This command tries to repeatedly execute a shell command in the |
---|
| 3603 | context of each of the used package of the current package. The |
---|
| 3604 | used packages are listed using the <b>cmt show uses</b> |
---|
| 3605 | command, which also indicates in which order the broadcast is |
---|
| 3606 | performed. When the <b>all_packages</b> option, the set of |
---|
| 3607 | packages reached by the broadcast is rather the same as the one shown |
---|
| 3608 | by the <b>cmt show packages</b> command, ie all <b>CMT</b> packages |
---|
| 3609 | and versions available throught the current <b>CMTPATH</b> list. |
---|
| 3610 | |
---|
| 3611 | <p>Typical uses of this <i>broadcast</i> operation could be:</p> |
---|
| 3612 | |
---|
| 3613 | <cmt:code> |
---|
| 3614 | csh> cmt broadcast cmt config |
---|
| 3615 | csh> cmt broadcast - gmake |
---|
| 3616 | csh> cmt broadcast '(cd ../; cvs -n update)' |
---|
| 3617 | </cmt:code> |
---|
| 3618 | |
---|
| 3619 | <p>The loop over used packages will stop at the first error |
---|
| 3620 | occurence in the application of the command, except if the |
---|
| 3621 | command was preceded by a '-' (minus) sign (similarly to the |
---|
| 3622 | make convention).</p> |
---|
| 3623 | |
---|
| 3624 | <p>It is possible to specify a list of selection or |
---|
| 3625 | exclusion criteria set onto the package path, using the |
---|
| 3626 | following options, right after the <b>broadcast</b> |
---|
| 3627 | keyword. These selection criteria may be combined (eg one |
---|
| 3628 | may combine the <i>begin</i> and <i>select</i> |
---|
| 3629 | modifiers)</p> |
---|
| 3630 | |
---|
| 3631 | <cmt:code> |
---|
| 3632 | sh> cmt broadcast -begin=Cm gmake (1) |
---|
| 3633 | sh> cmt broadcast -select=Cm gmake (2) |
---|
| 3634 | sh> cmt broadcast -select='/Cm/ /CSet/' gmake (3) |
---|
| 3635 | sh> cmt broadcast -select=Cm -exclude=Cmo gmake (4) |
---|
| 3636 | sh> cmt broadcast -local gmake (5) |
---|
| 3637 | sh> cmt broadcast -depth=<n> gmake (6) |
---|
| 3638 | sh> cmt broadcast -global gmake (7) |
---|
| 3639 | sh> cmt broadcast -all_packages gmake (8) |
---|
| 3640 | </cmt:code> |
---|
| 3641 | |
---|
| 3642 | <p>According to the option, the loop will only operate onto:</p> |
---|
| 3643 | |
---|
| 3644 | <ol> |
---|
| 3645 | <li>the first package which path contains the string |
---|
| 3646 | <b>"Cm"</b>, and then all other reachable packages (in |
---|
| 3647 | case other specifiers are used)</li> |
---|
| 3648 | |
---|
| 3649 | <li>the packages which path contains the string <b>"Cm"</b></li> |
---|
| 3650 | |
---|
| 3651 | <li>the packages which path contains either the string |
---|
| 3652 | <b>"/Cm/"</b> or the string <b>"/CSet/"</b></li> |
---|
| 3653 | |
---|
| 3654 | <li>the packages which path contains the string <b>"Cm"</b>, |
---|
| 3655 | but which does not contain the string <b>"Cmo"</b></li> |
---|
| 3656 | |
---|
| 3657 | <li>the packages at the same level as the current package</li> |
---|
| 3658 | |
---|
| 3659 | <li>the packages at the same level as the current package or |
---|
| 3660 | among the <n> first entries in the <b>CMTPATH</b> list</li> |
---|
| 3661 | |
---|
| 3662 | <li>the packages at any level of the CMTPATH search list</li> |
---|
| 3663 | |
---|
| 3664 | <li>all the packages and versions currently available |
---|
| 3665 | through the <b>CMTPATH</b> list</li> |
---|
| 3666 | </ol> |
---|
| 3667 | |
---|
| 3668 | <cmt:section title="Specifying the shell command"> |
---|
| 3669 | |
---|
| 3670 | <p>A priori any Unix or DOS shell command can be specified |
---|
| 3671 | in a boadcast command. However, it's important to |
---|
| 3672 | understand the order of the various parsing actions:</p> |
---|
| 3673 | |
---|
| 3674 | <ol> |
---|
| 3675 | <li>The current shell first parses the complete command line</li> |
---|
| 3676 | <li>CMT catches all possible options given to the broadcast command itself</li> |
---|
| 3677 | <li>CMT then gets the rest of the command line and makes it the shell command to be executed during the broadcast scan.</li> |
---|
| 3678 | <li>This command line may be subject to template substitution (see below) by CMT</li> |
---|
| 3679 | <li>Eventually the command line is passed to the local shell (which may then perform additional parsing actions)</li> |
---|
| 3680 | </ol> |
---|
| 3681 | |
---|
| 3682 | <p>Considering this complex sequence of parsing, it may be |
---|
| 3683 | appropriate to selectively enclose the shell command |
---|
| 3684 | passed to the broadcast action into quotes. It may even be |
---|
| 3685 | sometimes useful to have two levels of quotes</p> |
---|
| 3686 | |
---|
| 3687 | </cmt:section> |
---|
| 3688 | |
---|
| 3689 | <cmt:section title="Templates in the shell command"> |
---|
| 3690 | |
---|
| 3691 | <p>Similarly to what exists in the <a |
---|
| 3692 | href="#patterns">pattern</a> mechanism, some standard |
---|
| 3693 | <i>templated</i> values can be embedded inside the |
---|
| 3694 | command to be executed by the broadcast action. They take |
---|
| 3695 | a standard form of |
---|
| 3696 | <i><b><template-name></b></i>. These templates acquire |
---|
| 3697 | their value on each package effectively reached during the |
---|
| 3698 | broadcast scan, and the effective value is substituted |
---|
| 3699 | before launching the command. The possible templates are:</p> |
---|
| 3700 | |
---|
| 3701 | <table> |
---|
| 3702 | |
---|
| 3703 | <tr> |
---|
| 3704 | <td><b><package_cmtpath></b></td> |
---|
| 3705 | <td>The element in the CMTPATH search list where the package has been found</td> |
---|
| 3706 | </tr> |
---|
| 3707 | |
---|
| 3708 | <tr> |
---|
| 3709 | <td><b><package_offset></b></td> |
---|
| 3710 | <td>The directory offset to cmtpath</td> |
---|
| 3711 | </tr> |
---|
| 3712 | |
---|
| 3713 | <tr> |
---|
| 3714 | <td><b><package></b></td> |
---|
| 3715 | <td>The package name</td> |
---|
| 3716 | </tr> |
---|
| 3717 | |
---|
| 3718 | <tr> |
---|
| 3719 | <td><b><version></b></td> |
---|
| 3720 | <td>The version of the package</td> |
---|
| 3721 | </tr> |
---|
| 3722 | |
---|
| 3723 | </table> |
---|
| 3724 | |
---|
| 3725 | <p>The next example shows a typical broadcast command listing the |
---|
| 3726 | header files as expected in the conventional location |
---|
| 3727 | <b>../<package></b> :</p> |
---|
| 3728 | |
---|
| 3729 | <cmt:code> |
---|
| 3730 | > cmt broadcast 'ls ../<package>' |
---|
| 3731 | [...] |
---|
| 3732 | #-------------------------------------------------------------- |
---|
| 3733 | # Now trying [ ls ../GenzModuleEvent] in /afs/cern.ch/atlas/software/dist/6.3.0/Generators/GenzModuleEvent/GenzModuleEvent-00-00-09/cmt (149/609) |
---|
| 3734 | #-------------------------------------------------------------- |
---|
| 3735 | CVS KineHepMcmap.h |
---|
| 3736 | #-------------------------------------------------------------- |
---|
| 3737 | # Now trying [ ls ../Tauola_i] in /afs/cern.ch/atlas/software/dist/6.3.0/Generators/Tauola_i/Tauola_i-00-00-13/cmt (150/609) |
---|
| 3738 | #-------------------------------------------------------------- |
---|
| 3739 | CVS Jaki.icc Tauola_i.h Taurad.h config.h rn_tau.h tauola_i.inc |
---|
| 3740 | Jaki.h ReadPDGtable.h Tauola_i.icc Taurad.icc polhep.inc tauola_cblk.inc |
---|
| 3741 | #-------------------------------------------------------------- |
---|
| 3742 | # Now trying [ ls ../NavigationEvent] in /afs/cern.ch/atlas/software/dist/6.3.0/Reconstruction/NavigationEvent/NavigationEvent-00-00-04/cmt (151/609) |
---|
| 3743 | #-------------------------------------------------------------- |
---|
| 3744 | CVS INavigable.h INavigationCondition.h INavigationSelector.h INavigationToken.h NavigationToken.h |
---|
| 3745 | [...] |
---|
| 3746 | </cmt:code> |
---|
| 3747 | |
---|
| 3748 | <cmt:blockquote> |
---|
| 3749 | One should note that when templates are used in a |
---|
| 3750 | broadcast command, it's important to enclose the command |
---|
| 3751 | in quotes so as to inhibit any possible parsing of the |
---|
| 3752 | <b>< ></b> syntax by the shell. |
---|
| 3753 | </cmt:blockquote> |
---|
| 3754 | |
---|
| 3755 | </cmt:section> |
---|
| 3756 | |
---|
| 3757 | </cmt:section> |
---|
| 3758 | |
---|
| 3759 | <cmt:section title="cmt build <option>"> |
---|
| 3760 | |
---|
| 3761 | <p>The actions associated with the build options are |
---|
| 3762 | generally meant for internal use only, and users will |
---|
| 3763 | rarely (if ever!) apply them manually</p> |
---|
| 3764 | |
---|
| 3765 | <p>All build commands are generally meant to change the |
---|
| 3766 | current package (some file or set of files is |
---|
| 3767 | generated). Therefore a check against conflicting locks |
---|
| 3768 | (ie. a lock owned by another user) is performed by all |
---|
| 3769 | these commands prior to execute it.</p> |
---|
| 3770 | |
---|
| 3771 | <ul> |
---|
| 3772 | <li><b>[-nmake] constituent_makefile <<i>constituent-name</i>></b> |
---|
| 3773 | |
---|
| 3774 | <p>This command is internally used by <b>CMT</b> in the standard |
---|
| 3775 | Makefile.header fragment. It generates a specific makefile |
---|
| 3776 | fragment (named <<i>constituent-name</i>>.make) |
---|
| 3777 | which is used to re-build this fragment. </p> |
---|
| 3778 | |
---|
| 3779 | <p>All such constituent fragments are automatically |
---|
| 3780 | included from the main Makefile. </p> |
---|
| 3781 | |
---|
| 3782 | <p>Although this command is meant to be used internally |
---|
| 3783 | (and transparently) by <b>CMT</b> when the make command is run, a |
---|
| 3784 | developer may find useful in very rare cases to manually |
---|
| 3785 | re-generate the constituent fragment, using this command.</p> |
---|
| 3786 | |
---|
| 3787 | <p>The <b>-nmake</b> option (which must precede the |
---|
| 3788 | command) provides exactly the same features but in a |
---|
| 3789 | Windows/nmake context. In this case, all generated |
---|
| 3790 | makefiles are suffixed by <b>.nmake</b> instead of |
---|
| 3791 | <b>.make</b> for Unix environments. The main makefile is |
---|
| 3792 | expected to be named <b>NMake</b> and the standard header |
---|
| 3793 | is named <b>NMakefile.header</b></p> |
---|
| 3794 | |
---|
| 3795 | </li> |
---|
| 3796 | |
---|
| 3797 | <li><b>[-nmake] constituents_makefile</b> |
---|
| 3798 | |
---|
| 3799 | <p>This command is internally (and transparently) used by |
---|
| 3800 | <b>CMT</b> in the standard Makefile.header fragment, and when the |
---|
| 3801 | make command is run, to generate a specialized make |
---|
| 3802 | fragment containing all "cmt build constituent_makefile" |
---|
| 3803 | commands for a given package. </p> |
---|
| 3804 | |
---|
| 3805 | <p>The <b>-nmake</b> option (which must precede the |
---|
| 3806 | command) provides exactly the same feature but in a |
---|
| 3807 | Windows/nmake context. In this case, all generated |
---|
| 3808 | makefiles are suffixed by <b>.nmake</b> instead of |
---|
| 3809 | <b>.make</b> for Unix environments. The main makefile is |
---|
| 3810 | expected to be named <b>NMake</b> and the standard header |
---|
| 3811 | is named <b>NMakefile.header</b></p> |
---|
| 3812 | |
---|
| 3813 | </li> |
---|
| 3814 | |
---|
| 3815 | <li><b>dependencies</b> |
---|
| 3816 | |
---|
| 3817 | <p>This command is internally (and transparently) used by |
---|
| 3818 | <b>CMT</b> from the constituent specific fragment, and when the |
---|
| 3819 | make command is run, to generate a fragment containing the |
---|
| 3820 | dependencies required by a source file. </p> |
---|
| 3821 | |
---|
| 3822 | <p>This fragment contains a set of macro definitions (one |
---|
| 3823 | per constituent source file), each containing the set of |
---|
| 3824 | found dependencies. </p> |
---|
| 3825 | |
---|
| 3826 | </li> |
---|
| 3827 | |
---|
| 3828 | <li><b>library_links</b> |
---|
| 3829 | |
---|
| 3830 | <p>This command builds a local symbolic link towards all |
---|
| 3831 | exported libraries from the used packages. A package |
---|
| 3832 | exports its libraries through the |
---|
| 3833 | <b><<i>package</i>>_libraries</b> macro which should |
---|
| 3834 | contain the list of constituent names corresponding to |
---|
| 3835 | libraries that must be exported.</p> |
---|
| 3836 | |
---|
| 3837 | <cmt:code> |
---|
| 3838 | library Foo ... |
---|
| 3839 | library Foo-utils ... |
---|
| 3840 | ... |
---|
| 3841 | macro Foo_libraries "Foo Foo-utils" |
---|
| 3842 | </cmt:code> |
---|
| 3843 | |
---|
| 3844 | The corresponding <b>cmt remove library_links</b> command |
---|
| 3845 | will remove all these links. |
---|
| 3846 | |
---|
| 3847 | </li> |
---|
| 3848 | |
---|
| 3849 | <li><b>msdev</b> |
---|
| 3850 | |
---|
| 3851 | <p>This command generates workspace (.dsw) and project |
---|
| 3852 | (.dsp) files required for the MSDev tool. </p> |
---|
| 3853 | |
---|
| 3854 | </li> |
---|
| 3855 | |
---|
| 3856 | <li><b>vsnet</b> |
---|
| 3857 | |
---|
| 3858 | <p>This command generates workspace and project files |
---|
| 3859 | required for the Visual.net tool. </p> |
---|
| 3860 | |
---|
| 3861 | </li> |
---|
| 3862 | |
---|
| 3863 | <li><b>os9_makefile</b> |
---|
| 3864 | |
---|
| 3865 | <p>This command generates external dedicated |
---|
| 3866 | <i>makefile</i> fragments for each individual component of |
---|
| 3867 | the package (ie. libraries or executable applications) to |
---|
| 3868 | be used in OS9 context. It generates specific syntaxes for |
---|
| 3869 | the <b>OS9</b> operating systems.</p> |
---|
| 3870 | |
---|
| 3871 | <p>The output of this tool is a set of files (named with |
---|
| 3872 | the components' name and suffixed by <b>.os9make</b>) that |
---|
| 3873 | are meant to be <i>included</i> within the main |
---|
| 3874 | <b>Makefile</b> that the developer has to write anyhow.</p> |
---|
| 3875 | |
---|
| 3876 | <p>The syntax of the <b>cmt build os9_makefile</b> utility |
---|
| 3877 | is as follows : </p> |
---|
| 3878 | |
---|
| 3879 | <cmt:code> |
---|
| 3880 | sh> cmt build os9_makefile <package> |
---|
| 3881 | </cmt:code> |
---|
| 3882 | |
---|
| 3883 | </li> |
---|
| 3884 | |
---|
| 3885 | <li><b>prototype <source-file-name></b> |
---|
| 3886 | |
---|
| 3887 | <p>This command is internally (and transparently) used by |
---|
| 3888 | <b>CMT</b> from the constituent specific fragment, and when the |
---|
| 3889 | make command is run, to generate prototype header files |
---|
| 3890 | from C source files. </p> |
---|
| 3891 | |
---|
| 3892 | <p>The prototype header files (named <file-name>.ph) |
---|
| 3893 | will contain prototype definitions for every global entry |
---|
| 3894 | point defined in the corresponding C source file. </p> |
---|
| 3895 | |
---|
| 3896 | <p>The effective activation of this feature is controled |
---|
| 3897 | by the build strategy of <b>CMT</b>. The build strategy may be |
---|
| 3898 | freely and globally overridden from any &CMTrequirements; file, |
---|
| 3899 | using the <b>build_strategy</b> cmt statement, providing |
---|
| 3900 | either the "prototypes" or the "no_prototypes" values. </p> |
---|
| 3901 | |
---|
| 3902 | <p>In addition, any constituent may locally override this |
---|
| 3903 | strategy using the "-prototypes" or "-no_prototypes" |
---|
| 3904 | modifiers. </p> |
---|
| 3905 | |
---|
| 3906 | </li> |
---|
| 3907 | |
---|
| 3908 | <li><b>readme</b> |
---|
| 3909 | |
---|
| 3910 | <p>This command generates a README.html file into the cmt |
---|
| 3911 | branch of the referenced package. This html file will |
---|
| 3912 | include </p> |
---|
| 3913 | |
---|
| 3914 | <ul> |
---|
| 3915 | |
---|
| 3916 | <li>a table containing URLs to equivalent pages for |
---|
| 3917 | all used packages, </li> |
---|
| 3918 | |
---|
| 3919 | <li>a copy of the local README file (if it exists). </li> |
---|
| 3920 | |
---|
| 3921 | </ul> |
---|
| 3922 | |
---|
| 3923 | </li> |
---|
| 3924 | |
---|
| 3925 | <li><b>tag_makefile</b> |
---|
| 3926 | |
---|
| 3927 | <p> This command produces onto the standard output, the |
---|
| 3928 | exhaustive list of all macros controled by <b>CMT</b>, |
---|
| 3929 | ie. those defined in the requirements files as well as the |
---|
| 3930 | standard macros internally built by <b>CMT</b>, taking |
---|
| 3931 | into account all used packages.</p> |
---|
| 3932 | |
---|
| 3933 | </li> |
---|
| 3934 | |
---|
| 3935 | </ul> |
---|
| 3936 | |
---|
| 3937 | </cmt:section> |
---|
| 3938 | |
---|
| 3939 | <cmt:section title="cmt check configuration"> |
---|
| 3940 | |
---|
| 3941 | This command reads the hierarchy of requirements files |
---|
| 3942 | referenced by a package, check them, and signals syntax |
---|
| 3943 | errors, version conflicts or other configuration problems. |
---|
| 3944 | |
---|
| 3945 | <p>An empty output means that everything is fine. </p> |
---|
| 3946 | |
---|
| 3947 | </cmt:section> |
---|
| 3948 | |
---|
| 3949 | <cmt:section title="cmt check files <reference-file> <new-file>"> |
---|
| 3950 | |
---|
| 3951 | This command compares the reference file to the new file, and |
---|
| 3952 | substitues the reference file by the new one if they are |
---|
| 3953 | different. |
---|
| 3954 | |
---|
| 3955 | <p>If substitution is performed, a copy (with additional |
---|
| 3956 | extension <b>sav</b>) is produced. </p> |
---|
| 3957 | |
---|
| 3958 | </cmt:section> |
---|
| 3959 | |
---|
| 3960 | <cmt:section title="cmt checkout ..."> |
---|
| 3961 | |
---|
| 3962 | See the <a href="#Using cvs together with CMT">paragraph</a> |
---|
| 3963 | on how to use cvs together with <b>CMT</b>, and more specifically the |
---|
| 3964 | details on <a href="#Checking a package out from a cvs repository">checkout oprations</a>. |
---|
| 3965 | |
---|
| 3966 | </cmt:section> |
---|
| 3967 | |
---|
| 3968 | <cmt:section title="cmt co ..."> |
---|
| 3969 | |
---|
| 3970 | This is simply a short cut to the <b>cmt checkout</b> command. |
---|
| 3971 | |
---|
| 3972 | </cmt:section> |
---|
| 3973 | |
---|
| 3974 | <cmt:section title="cmt cleanup [-csh|-sh]"> |
---|
| 3975 | |
---|
| 3976 | This command generates (to the standard output) a set of shell |
---|
| 3977 | commands (either for csh or sh shell families) meant to unset |
---|
| 3978 | all environment variables specified in the &CMTrequirements; files |
---|
| 3979 | of the used packages. |
---|
| 3980 | |
---|
| 3981 | <p>This command is internally used in the cleanup.[c]sh shell |
---|
| 3982 | script, itself generated by the <b>cmt config</b> command. </p> |
---|
| 3983 | |
---|
| 3984 | </cmt:section> |
---|
| 3985 | |
---|
| 3986 | <cmt:section title="cmt config"> |
---|
| 3987 | |
---|
| 3988 | <p>This command (re-)generates the setup scripts and the |
---|
| 3989 | manimal Makefile (when it does not exist yet or have been lost).</p> |
---|
| 3990 | |
---|
| 3991 | <cmt:code> |
---|
| 3992 | csh> cd ~/Packages/Foo/v1/cmt |
---|
| 3993 | csh> cmt config |
---|
| 3994 | </cmt:code> |
---|
| 3995 | |
---|
| 3996 | <p>To be properly operated, one must <i>already</i> be in |
---|
| 3997 | the <b>cmt</b> or <b>mgr</b> branch of a package (where the |
---|
| 3998 | &CMTrequirements; file can |
---|
| 3999 | be found).</p> |
---|
| 4000 | |
---|
| 4001 | <p>This command also performs some cleanup operations |
---|
| 4002 | (eg. removing all makefile fragments previously |
---|
| 4003 | generated). Generally speaking, one may say that this |
---|
| 4004 | command restores the CMT-related files to their original state (ie |
---|
| 4005 | before any document generation) </p> |
---|
| 4006 | |
---|
| 4007 | <p>The situations in which it is useful to run this command are:</p> |
---|
| 4008 | |
---|
| 4009 | <ul> |
---|
| 4010 | |
---|
| 4011 | <li>When the setup or cleanup scripts have been lost</li> |
---|
| 4012 | |
---|
| 4013 | <li>When the minimal Makefile have been lost</li> |
---|
| 4014 | |
---|
| 4015 | <li>When the version of <b>CMT</b> is changed</li> |
---|
| 4016 | |
---|
| 4017 | <li>After restoring a package from CVS</li> |
---|
| 4018 | |
---|
| 4019 | <li>After having manually changed the directory structure |
---|
| 4020 | of a package (using a manual copy operation, or renaming |
---|
| 4021 | one of its parent directory, such as the version |
---|
| 4022 | directory)</li> |
---|
| 4023 | |
---|
| 4024 | </ul> |
---|
| 4025 | |
---|
| 4026 | </cmt:section> |
---|
| 4027 | |
---|
| 4028 | <cmt:section title="cmt create <package> <version> [<area>]"> |
---|
| 4029 | |
---|
| 4030 | <p> |
---|
| 4031 | This command creates a new package or a new version of a package</p> |
---|
| 4032 | |
---|
| 4033 | <cmt:code> |
---|
| 4034 | csh> cmt create Foo v1 |
---|
| 4035 | </cmt:code> |
---|
| 4036 | |
---|
| 4037 | or: |
---|
| 4038 | |
---|
| 4039 | <cmt:code> |
---|
| 4040 | csh> cmt create Foo v1 ~/dev |
---|
| 4041 | </cmt:code> |
---|
| 4042 | |
---|
| 4043 | <p>In the first mode (ie. without the <i>area</i> argument) |
---|
| 4044 | the package will be created in the default path.</p> |
---|
| 4045 | |
---|
| 4046 | <p>The second mode explicitly provides an alternate path.</p> |
---|
| 4047 | |
---|
| 4048 | <p>A minimal configuration is installed for this new package:</p> |
---|
| 4049 | |
---|
| 4050 | <ul> |
---|
| 4051 | |
---|
| 4052 | <li>An <b>src</b> and an <b>cmt</b> branch</li> |
---|
| 4053 | |
---|
| 4054 | <li>A very minimal requirements file</li> |
---|
| 4055 | |
---|
| 4056 | <li>The setup and cleanup shell scripts</li> |
---|
| 4057 | |
---|
| 4058 | <li>The minimal Makefile</li> |
---|
| 4059 | |
---|
| 4060 | </ul> |
---|
| 4061 | |
---|
| 4062 | </cmt:section> |
---|
| 4063 | |
---|
| 4064 | <cmt:section title="cmt filter <in-file> <out-file>"> |
---|
| 4065 | |
---|
| 4066 | This command reads <in-file>, substitutes all occurences |
---|
| 4067 | of macro references (taking either the form |
---|
| 4068 | <b>$(<i>macro-name</i>)</b> or <b>${<i>macro-name</i>}</b> |
---|
| 4069 | ) by values deduced from corresponding macro specifications |
---|
| 4070 | found in the &CMTrequirements; files, and writes the result into |
---|
| 4071 | <out-file>. |
---|
| 4072 | |
---|
| 4073 | <p>This mechanism is widely internally used by <b>CMT</b>, especially |
---|
| 4074 | for instanciating make fragments. Then, users may use it for |
---|
| 4075 | any kind of document, including maual generation of MSDev |
---|
| 4076 | configuration files, etc... </p> |
---|
| 4077 | |
---|
| 4078 | </cmt:section> |
---|
| 4079 | |
---|
| 4080 | <cmt:section title="cmt help | --help"> |
---|
| 4081 | |
---|
| 4082 | This command shows the list of options of the <b>cmt</b> driver. |
---|
| 4083 | |
---|
| 4084 | </cmt:section> |
---|
| 4085 | |
---|
| 4086 | <cmt:section title="cmt lock [ <package> <version> [<area>] ]"> |
---|
| 4087 | |
---|
| 4088 | This command tries to set a lock onto the current package (or onto the |
---|
| 4089 | specified package). This consists in the following operations: |
---|
| 4090 | |
---|
| 4091 | <p></p> |
---|
| 4092 | |
---|
| 4093 | <ol> |
---|
| 4094 | |
---|
| 4095 | <li>Check if a conflicting lock is already set onto this |
---|
| 4096 | package (ie. a lock owned by another user).</li> |
---|
| 4097 | |
---|
| 4098 | <p></p> |
---|
| 4099 | |
---|
| 4100 | <li>If not, then install a small text file named <b>lock.cmt</b> into the |
---|
| 4101 | <b>cmt/mgr</b> branch of the package, containing the following text: |
---|
| 4102 | |
---|
| 4103 | <cmt:code> |
---|
| 4104 | locked by <user-name> date <now> |
---|
| 4105 | </cmt:code> |
---|
| 4106 | |
---|
| 4107 | <p></p> |
---|
| 4108 | </li> |
---|
| 4109 | |
---|
| 4110 | <li>Run a shell command described in the macro named <b>lock_command</b> meant to install physical locks onto all files for this version of this package. A typical definition for this macro could be: |
---|
| 4111 | |
---|
| 4112 | <cmt:code> |
---|
| 4113 | macro lock_command "chmod -R a-w ../*" \ |
---|
| 4114 | WIN32 "attrib /S /D +R ../*" |
---|
| 4115 | </cmt:code> |
---|
| 4116 | |
---|
| 4117 | </li> |
---|
| 4118 | |
---|
| 4119 | </ol> |
---|
| 4120 | |
---|
| 4121 | </cmt:section> |
---|
| 4122 | |
---|
| 4123 | <cmt:section title="cmt remove <package> <version> [<area>]"> |
---|
| 4124 | |
---|
| 4125 | This command removes one version of the specified package. If |
---|
| 4126 | the package does not contain a conflicting lock, and if the user is |
---|
| 4127 | granted enough access rights to remove files, <i>all</i> files below |
---|
| 4128 | the version directory will be definitively removed. Therefore |
---|
| 4129 | this command should be used with as much care as possible. |
---|
| 4130 | |
---|
| 4131 | <p>The arguments needed to reach the package version to be |
---|
| 4132 | removed are the same as the ones whic had been used to create it.</p> |
---|
| 4133 | |
---|
| 4134 | <p>If the removed version is the last version of this package, |
---|
| 4135 | (and only if its directory is really empty) the package directory itself |
---|
| 4136 | will be deleted.</p> |
---|
| 4137 | |
---|
| 4138 | </cmt:section> |
---|
| 4139 | |
---|
| 4140 | <cmt:section title="cmt remove library_links"> |
---|
| 4141 | |
---|
| 4142 | This command removes symbolic links towards all imported |
---|
| 4143 | libraries which had been installed using the <b><a |
---|
| 4144 | href="#build">cmt build library_links</a></b> command. This |
---|
| 4145 | command is generally transparently executed when one runs |
---|
| 4146 | <b>gmake clean</b> |
---|
| 4147 | |
---|
| 4148 | </cmt:section> |
---|
| 4149 | |
---|
| 4150 | <cmt:section title="cmt run 'shell-command'"> |
---|
| 4151 | |
---|
| 4152 | This command runs any shell command, in the context of the |
---|
| 4153 | current package. |
---|
| 4154 | |
---|
| 4155 | <p>In particular all environment variables defined in |
---|
| 4156 | requirements file are first set before running the |
---|
| 4157 | command. This may be seen as a generic application |
---|
| 4158 | launcher.</p> |
---|
| 4159 | |
---|
| 4160 | <p>This may be combined with the global options |
---|
| 4161 | -pack=<i>package</i>, -version=<i>version</i>, |
---|
| 4162 | -path=<i>access-path</i>, to give a direct access to any |
---|
| 4163 | package context. </p> |
---|
| 4164 | |
---|
| 4165 | </cmt:section> |
---|
| 4166 | |
---|
| 4167 | <cmt:section title="cmt set version <version>"> |
---|
| 4168 | |
---|
| 4169 | This command creates and/or fills in the |
---|
| 4170 | <b>version.cmt</b> file for a package structured without |
---|
| 4171 | the version directory. |
---|
| 4172 | |
---|
| 4173 | <p>This command has no effect when run in the context of a |
---|
| 4174 | package structured <i>with</i> the version directory</p> |
---|
| 4175 | |
---|
| 4176 | <p>This command must be run while being in the context of |
---|
| 4177 | one CMT package.</p> |
---|
| 4178 | |
---|
| 4179 | </cmt:section> |
---|
| 4180 | |
---|
| 4181 | <cmt:section title="cmt set versions"> |
---|
| 4182 | |
---|
| 4183 | This command applies recursively the <b>cmt set version |
---|
| 4184 | ...</b> command onto all used packages using a broadcast operation. |
---|
| 4185 | |
---|
| 4186 | <p>Packages reached during the broadcast scan acquire |
---|
| 4187 | their version from the original use statement. This is |
---|
| 4188 | this specified version which will be stored inside the |
---|
| 4189 | <b>version.cmt</b> files</p> |
---|
| 4190 | |
---|
| 4191 | </cmt:section> |
---|
| 4192 | |
---|
| 4193 | <cmt:section title="cmt setup [-csh|-sh|-bat]"> |
---|
| 4194 | |
---|
| 4195 | This command generates (to the standard output) a set of shell |
---|
| 4196 | commands (either for csh, sh or bat shell families) meant to |
---|
| 4197 | set all environment variables specified in the <a HREF="#The |
---|
| 4198 | requirements file">requirements</a> files of the used |
---|
| 4199 | packages. |
---|
| 4200 | |
---|
| 4201 | <p>This command is internally used in the setup.[c]sh or |
---|
| 4202 | setup.bat shell script, itself generated by the <b>cmt |
---|
| 4203 | config</b> command.</p> |
---|
| 4204 | |
---|
| 4205 | </cmt:section> |
---|
| 4206 | |
---|
| 4207 | <cmt:section title="cmt show <option>"> |
---|
| 4208 | |
---|
| 4209 | <ul> |
---|
| 4210 | <li><b>all_tags</b> </li> |
---|
| 4211 | |
---|
| 4212 | <p>This command displays all currently defined tags, |
---|
| 4213 | even when not currenty active</p> |
---|
| 4214 | |
---|
| 4215 | <li><b>applied_patterns</b> </li> |
---|
| 4216 | |
---|
| 4217 | <p>This command displays all patterns actually applied |
---|
| 4218 | in the current package</p> |
---|
| 4219 | |
---|
| 4220 | <li><b>author</b> </li> |
---|
| 4221 | |
---|
| 4222 | <li><b>branches</b> </li> |
---|
| 4223 | |
---|
| 4224 | <li><b>clients <package> [ <version> ]</b> |
---|
| 4225 | |
---|
| 4226 | <p>This command displays all packages that express an |
---|
| 4227 | explicit <strong>use</strong> statement onto the specified |
---|
| 4228 | package. If no version is specified on the argument list, |
---|
| 4229 | then all uses of that package are displayed.</p> |
---|
| 4230 | |
---|
| 4231 | <p></p> |
---|
| 4232 | </li> |
---|
| 4233 | |
---|
| 4234 | <li><b>constituent_names</b> </li> |
---|
| 4235 | |
---|
| 4236 | <li><b>constituents</b> </li> |
---|
| 4237 | |
---|
| 4238 | <li><b>cycles</b> </li> |
---|
| 4239 | |
---|
| 4240 | <p>This command displays all cycles in the use graph |
---|
| 4241 | of the current package. Although CMT smoothly accepts |
---|
| 4242 | such cycles, still it is generally a bad practice to |
---|
| 4243 | have cycles in a use graph, because in front of a |
---|
| 4244 | cycle CMT can never decide on the prefered entry point |
---|
| 4245 | in the cycle, leading to somewhat unpredictable |
---|
| 4246 | results, eg in constructing the use_linkopts macro.</p> |
---|
| 4247 | |
---|
| 4248 | <li><b>uses</b> </li> |
---|
| 4249 | |
---|
| 4250 | <li><b>use_paths <target-package></b> </li> |
---|
| 4251 | |
---|
| 4252 | <p>This command displays all possible paths between |
---|
| 4253 | the current package and the specified used target |
---|
| 4254 | package.</p> |
---|
| 4255 | |
---|
| 4256 | <p>In particular this will detect if a package has no |
---|
| 4257 | access to another one, due to private use |
---|
| 4258 | statements</p> |
---|
| 4259 | |
---|
| 4260 | |
---|
| 4261 | <li><b>fragment <name></b> |
---|
| 4262 | |
---|
| 4263 | <p>This command displays the actual location where the |
---|
| 4264 | specified make fragment is currently found by <b>CMT</b>, |
---|
| 4265 | taking into account possible overridden definitions.</p> |
---|
| 4266 | |
---|
| 4267 | <li><b>fragments</b> </li> |
---|
| 4268 | |
---|
| 4269 | <li><b>groups</b> |
---|
| 4270 | |
---|
| 4271 | <p>This command displays all groups possibly defined in |
---|
| 4272 | constituents of the current package (using the |
---|
| 4273 | <b>-group=<<i>group-name</i>></b> option).</p> |
---|
| 4274 | |
---|
| 4275 | <p></p> |
---|
| 4276 | |
---|
| 4277 | <li><b>languages</b> </li> |
---|
| 4278 | |
---|
| 4279 | <li><b>macro <name></b> |
---|
| 4280 | |
---|
| 4281 | <p>This command displays a quite detailed explanation on the value |
---|
| 4282 | assigned to the macro specified as the additional argument. It |
---|
| 4283 | presents in particular each intermediate assignments made to |
---|
| 4284 | this macro by the hierarchy of used statements, as well as the |
---|
| 4285 | final result of these assignment operations. </p> |
---|
| 4286 | |
---|
| 4287 | <p>By adding a <b>-tag=<tag></b> option to this command, it |
---|
| 4288 | is possible to simulate the behaviour of this command in |
---|
| 4289 | another context, without actually going to a machine or an |
---|
| 4290 | operating system where this configuration is defined. </p> |
---|
| 4291 | |
---|
| 4292 | <p></p> |
---|
| 4293 | </li> |
---|
| 4294 | |
---|
| 4295 | <li><b>macro_value <name></b> |
---|
| 4296 | |
---|
| 4297 | <p>This command displays the raw value assigned to the macro |
---|
| 4298 | specified as the additional argument. It only presents the final |
---|
| 4299 | result of the assignment operations performed by used packages. </p> |
---|
| 4300 | |
---|
| 4301 | <p>By adding a <b>-tag=<tag></b> option to this command, it |
---|
| 4302 | is possible to simulate the behaviour of this command in |
---|
| 4303 | another context, without actually going to a machine or an |
---|
| 4304 | operating system where this configuration is defined.</p> |
---|
| 4305 | |
---|
| 4306 | <p>The typical usage of the <b>show macro_value</b> command is |
---|
| 4307 | to get at the shell level (rather than within a |
---|
| 4308 | <b>Makefile</b>) the value of a macro definition, providing |
---|
| 4309 | means of accessing them (quite similarly to an environment |
---|
| 4310 | variable) : </p> |
---|
| 4311 | |
---|
| 4312 | <cmt:code> |
---|
| 4313 | csh> set compiler=`cmt show macro_value cppcomp` |
---|
| 4314 | csh> ${compiler} .... |
---|
| 4315 | </cmt:code> |
---|
| 4316 | |
---|
| 4317 | </li> |
---|
| 4318 | |
---|
| 4319 | <li><b>macros</b> |
---|
| 4320 | |
---|
| 4321 | <p>This command extracts from the <b>&CMTrequirements;</b> |
---|
| 4322 | file(s) the complete set of macro definitions, selects the |
---|
| 4323 | appropriate <i>tag</i> definition (or uses the one |
---|
| 4324 | provided in the <b>-tag=<tag></b> option) and |
---|
| 4325 | displays the effective macro values corresponding to this |
---|
| 4326 | tag. </p> |
---|
| 4327 | |
---|
| 4328 | <p>This command is typically used to show the effective list of |
---|
| 4329 | macros used when running make and can be also used to build, |
---|
| 4330 | as an argument list, the make command as follows : </p> |
---|
| 4331 | |
---|
| 4332 | <cmt:code> |
---|
| 4333 | csh> eval make `cmt show macros` |
---|
| 4334 | </cmt:code> |
---|
| 4335 | |
---|
| 4336 | <p>This use of <b>cmt show macros</b> is directly installed |
---|
| 4337 | within the default target provided in the standard |
---|
| 4338 | <b>Makefile.header</b> file. Therefore if this file is |
---|
| 4339 | included into the package's <b>Makefile</b>, macro |
---|
| 4340 | definitions provided in the &CMTrequirements; files (the one of the |
---|
| 4341 | currently built package as well as the ones of the used |
---|
| 4342 | packages) will be expanded and provided as arguments to make. </p> |
---|
| 4343 | |
---|
| 4344 | <p>By adding a <b>-tag=<tag></b> option to this command, it |
---|
| 4345 | is possible to simulate the behaviour of this command in |
---|
| 4346 | another context, without atcually going to a machine or an |
---|
| 4347 | operating system where this configuration is defined. </p> |
---|
| 4348 | |
---|
| 4349 | </li> |
---|
| 4350 | |
---|
| 4351 | <li><b>manager</b> </li> |
---|
| 4352 | |
---|
| 4353 | <li><b>packages</b> |
---|
| 4354 | |
---|
| 4355 | <p>This command displays all packages (and all versions of |
---|
| 4356 | them) currently reachable through the current <a |
---|
| 4357 | href="#Localizing a package">access path</a> definition |
---|
| 4358 | (which can be displayed using the <b>cmt show path</b> |
---|
| 4359 | command).</p> |
---|
| 4360 | |
---|
| 4361 | </li> |
---|
| 4362 | |
---|
| 4363 | <li><b>path</b> |
---|
| 4364 | |
---|
| 4365 | <p>This command displays the complete and effective <a |
---|
| 4366 | href="#Localizing a package">access path</a> currently |
---|
| 4367 | defined using any possible alternate way.</p> |
---|
| 4368 | |
---|
| 4369 | </li> |
---|
| 4370 | |
---|
| 4371 | <li><b>pattern <name></b> |
---|
| 4372 | |
---|
| 4373 | <p>This command displays how and where the specified |
---|
| 4374 | pattern is defined, and which packages do apply it.</p></li> |
---|
| 4375 | |
---|
| 4376 | </li> |
---|
| 4377 | |
---|
| 4378 | <li><b>patterns</b> |
---|
| 4379 | |
---|
| 4380 | <p>This command displays all pattern definitions.</p></li> |
---|
| 4381 | |
---|
| 4382 | </li> |
---|
| 4383 | |
---|
| 4384 | <li><b>pwd</b> |
---|
| 4385 | |
---|
| 4386 | <p>This command displays a filtered version of the |
---|
| 4387 | standard <b>pwd</b> unix command. The applied filter takes |
---|
| 4388 | into account the set of aliases installed in the standard |
---|
| 4389 | configuration file located in |
---|
| 4390 | <b>${CMTROOT}/mgr/cmt_mount_filter</b>.</p> |
---|
| 4391 | |
---|
| 4392 | <p>This configuration file contains a set of path aliases |
---|
| 4393 | (one per line) each proposing a translation for |
---|
| 4394 | non-portable file paths (imposed by mount constraints on |
---|
| 4395 | some contexts).</p> |
---|
| 4396 | |
---|
| 4397 | </li> |
---|
| 4398 | |
---|
| 4399 | <li><b>set_value <name></b> </li> |
---|
| 4400 | |
---|
| 4401 | <li><b>set <name></b> </li> |
---|
| 4402 | |
---|
| 4403 | <li><b>sets</b> </li> |
---|
| 4404 | |
---|
| 4405 | <li><b>strategies</b> </li> |
---|
| 4406 | |
---|
| 4407 | <li><b>tags</b> </li> |
---|
| 4408 | |
---|
| 4409 | <p>This command displays all currently <i>active</i> |
---|
| 4410 | tags, and what part of the configuration actually |
---|
| 4411 | activates them</p> |
---|
| 4412 | |
---|
| 4413 | <li><b>uses</b> |
---|
| 4414 | |
---|
| 4415 | <p>This command displays a quite comprehensive and detailed |
---|
| 4416 | explanation of the hierarchy of use statements, with the |
---|
| 4417 | effective selection made between possibly compatible versions. </p> |
---|
| 4418 | |
---|
| 4419 | <cmt:code> |
---|
| 4420 | <i><font face="courier new, courier" COLOR="#007700"># use Cm v7r11 |
---|
| 4421 | # use CSet v2r5 |
---|
| 4422 | # use OPACS v3 |
---|
| 4423 | # use Ci v5r2 |
---|
| 4424 | # use CSet v2r5 |
---|
| 4425 | # |
---|
| 4426 | # Selection : |
---|
| 4427 | use CMT v1r14 /lal |
---|
| 4428 | use CSet v2r5 (/lal) |
---|
| 4429 | use Ci v5r2 (/lal) |
---|
| 4430 | use OPACS v3 (/lal) |
---|
| 4431 | use Cm v7r11 (/lal)</font></i> |
---|
| 4432 | </cmt:code> |
---|
| 4433 | |
---|
| 4434 | <p>The <b>-quiet</b> option may be used to remove from the |
---|
| 4435 | output, the comments (beginning with the <b>#</b> |
---|
| 4436 | character), so as to display a simple list of used packages, |
---|
| 4437 | starting from the deepest uses.</p> |
---|
| 4438 | |
---|
| 4439 | </li> |
---|
| 4440 | |
---|
| 4441 | <li><b>version</b> |
---|
| 4442 | |
---|
| 4443 | <p>This command displays the version tag of the current package.</p> |
---|
| 4444 | |
---|
| 4445 | </li> |
---|
| 4446 | |
---|
| 4447 | <li><b>versions <name></b> |
---|
| 4448 | |
---|
| 4449 | <p>This command displays the reachable versions of the |
---|
| 4450 | specified package, looking at the current access paths.</p> |
---|
| 4451 | |
---|
| 4452 | </li> |
---|
| 4453 | |
---|
| 4454 | </ul> |
---|
| 4455 | |
---|
| 4456 | </cmt:section> |
---|
| 4457 | |
---|
| 4458 | <cmt:section title="cmt system"> |
---|
| 4459 | |
---|
| 4460 | This command displays the current value assigned by default to |
---|
| 4461 | the <b>CMTCONFIG</b> environment variable. |
---|
| 4462 | |
---|
| 4463 | </cmt:section> |
---|
| 4464 | |
---|
| 4465 | <cmt:section title="cmt unlock [ <package> <version> [<area>] ]"> |
---|
| 4466 | |
---|
| 4467 | This command tries to remove a lock from the current package (or from the |
---|
| 4468 | specified package). This consists in the following operations: |
---|
| 4469 | |
---|
| 4470 | <p> |
---|
| 4471 | <ol> |
---|
| 4472 | |
---|
| 4473 | <li>Check if a conflicting lock is already set onto this |
---|
| 4474 | package (ie. a lock owned by another user). |
---|
| 4475 | </li> |
---|
| 4476 | |
---|
| 4477 | <li>If not, then remove the text file named <b>lock.cmt</b> from the |
---|
| 4478 | <b>cmt/mgr</b> branch of the package. |
---|
| 4479 | |
---|
| 4480 | </li> |
---|
| 4481 | |
---|
| 4482 | <li>Run a shell command described in the macro named <b>unlock_command</b> meant to remove physical locks from all files for this version of this package. A typical definition for this macro could be: |
---|
| 4483 | |
---|
| 4484 | <cmt:code> |
---|
| 4485 | macro unlock_command "chmod -R g+w ../*" \ |
---|
| 4486 | WIN32 "attrib /S /D -R ../*" |
---|
| 4487 | </cmt:code> |
---|
| 4488 | </li> |
---|
| 4489 | </ol> |
---|
| 4490 | </p> |
---|
| 4491 | |
---|
| 4492 | </cmt:section> |
---|
| 4493 | |
---|
| 4494 | <cmt:section title="cmt version | --version"> |
---|
| 4495 | |
---|
| 4496 | This command shows the current verion of <b>CMT</b>, including (if |
---|
| 4497 | applicable) the actual patch level. This always corresponds to |
---|
| 4498 | the corresponding CVS tag assigned to <b>CMT</b> sources. |
---|
| 4499 | |
---|
| 4500 | </cmt:section> |
---|
| 4501 | |
---|
| 4502 | <cmt:section title="cmt cvstags <module>"> |
---|
| 4503 | |
---|
| 4504 | (see the section on <i>how tu use </i><b>CVS</b><i>together |
---|
| 4505 | with CMT</i> for more details on this command) |
---|
| 4506 | |
---|
| 4507 | </cmt:section> |
---|
| 4508 | |
---|
| 4509 | <cmt:section title="cmt cvsbranches <module>"> |
---|
| 4510 | |
---|
| 4511 | </cmt:section> |
---|
| 4512 | |
---|
| 4513 | <cmt:section title="cmt cvssubpackages <module>"> |
---|
| 4514 | |
---|
| 4515 | </cmt:section> |
---|
| 4516 | |
---|
| 4517 | </cmt:section> |
---|
| 4518 | |
---|
| 4519 | <cmt:section title="The setup and cleanup scripts"> |
---|
| 4520 | |
---|
| 4521 | They are produced by the <b>cmt config</b> command and their |
---|
| 4522 | contents is built according to the specifications stored in the |
---|
| 4523 | <b>&CMTrequirements;</b> file. |
---|
| 4524 | |
---|
| 4525 | <p>One flavour of these scripts is generated per shell family |
---|
| 4526 | (<b>csh</b>, <b>sh</b> and <b>bat</b>), yielding the following |
---|
| 4527 | scripts :</p> |
---|
| 4528 | |
---|
| 4529 | <cmt:code> |
---|
| 4530 | setup.csh |
---|
| 4531 | setup.sh |
---|
| 4532 | setup.bat |
---|
| 4533 | cleanup.csh |
---|
| 4534 | cleanup.sh |
---|
| 4535 | </cmt:code> |
---|
| 4536 | |
---|
| 4537 | <p>The main sections installed within a setup script are : </p> |
---|
| 4538 | |
---|
| 4539 | <ol> |
---|
| 4540 | <li> |
---|
| 4541 | Connection to the current version of the <b>CMT</b> package. |
---|
| 4542 | </li> |
---|
| 4543 | |
---|
| 4544 | <li> Setting the set of user defined public variables |
---|
| 4545 | specified in the &CMTrequirements; file (including those |
---|
| 4546 | defined by all used packages). This is achieved by running |
---|
| 4547 | the <b>cmt setup</b> utility into a temporary file and |
---|
| 4548 | running this temporary file. </li> |
---|
| 4549 | |
---|
| 4550 | <li> |
---|
| 4551 | Activation of the user defined setup and cleanup scripts |
---|
| 4552 | (those specified using the <b>setup_script</b> and |
---|
| 4553 | <b>cleanup_script</b> statements). |
---|
| 4554 | </li> |
---|
| 4555 | </ol> |
---|
| 4556 | |
---|
| 4557 | It should be noted that these setup scripts do <i>not</i> |
---|
| 4558 | contain machine specific information (due to the online use of |
---|
| 4559 | the <b>cmt setup</b> command). Therefore, it is perfectly |
---|
| 4560 | possible to use the same setup script on various platforms (as |
---|
| 4561 | soon as they share the directories) and this also shows that the |
---|
| 4562 | configuration operation (the <b>cmt config</b> command) is |
---|
| 4563 | required only once for a set of multiple platforms sharing a |
---|
| 4564 | development area. |
---|
| 4565 | |
---|
| 4566 | </cmt:section> |
---|
| 4567 | |
---|
| 4568 | <cmt:section title="cmt build prototype"> |
---|
| 4569 | |
---|
| 4570 | This command is only provided for development of <b>C</b> |
---|
| 4571 | modules. It generates a <b>C</b> header file containing the |
---|
| 4572 | set of prototype statements for all public functions of a given |
---|
| 4573 | module. Its output is a file with the same name as the input |
---|
| 4574 | source (given as the argument) and suffixed with <b>.ph</b>. |
---|
| 4575 | |
---|
| 4576 | <p>The generated prototype header file is meant to be included |
---|
| 4577 | whereever it is needed (in the module file itself for instance). </p> |
---|
| 4578 | |
---|
| 4579 | <p>A typical example of the use of <b>cmt build prototype</b> |
---|
| 4580 | could be : </p> |
---|
| 4581 | |
---|
| 4582 | <cmt:code> |
---|
| 4583 | csh> cd ../src |
---|
| 4584 | csh> cmt build prototype FooA.c |
---|
| 4585 | <i><font face="courier new, courier" COLOR="#007700">Building FooA.ph </font></i> |
---|
| 4586 | </cmt:code> |
---|
| 4587 | |
---|
| 4588 | <p>Running <b>cmt build prototype</b> will only produce a new |
---|
| 4589 | prototype header file if the output is actually different from |
---|
| 4590 | the existing one (if it exists) in order to avoid confusing |
---|
| 4591 | <i>make</i> checks. </p> |
---|
| 4592 | |
---|
| 4593 | <p>The effective use of this facility (which may not be |
---|
| 4594 | appropriate in all projects) is controlled by one option of the |
---|
| 4595 | build strategy, which can take one of the two values:</p> |
---|
| 4596 | |
---|
| 4597 | <cmt:code> |
---|
| 4598 | build_strategy prototypes |
---|
| 4599 | build_strategy no_prototypes |
---|
| 4600 | </cmt:code> |
---|
| 4601 | |
---|
| 4602 | <p>In addition to this global strategy specification, each |
---|
| 4603 | application or library may individually override it using the |
---|
| 4604 | <b>-prototypes</b> or <b>-no_prototypes</b> options.</p> |
---|
| 4605 | |
---|
| 4606 | <p>Lastly, the actual behaviour of the prototype generator is |
---|
| 4607 | defined in the standard make macro <b>build_prototype</b> (which |
---|
| 4608 | default to call the <b>cmt build prototype</b> command, allowing |
---|
| 4609 | a user defined behavious to this feature)</p> |
---|
| 4610 | |
---|
| 4611 | </cmt:section> |
---|
| 4612 | </cmt:section> |
---|
| 4613 | |
---|
| 4614 | <cmt:section title="Using cvs together with CMT"> |
---|
| 4615 | |
---|
| 4616 | <p>Nothing special is apriori required by <b>CMT</b> with respect to |
---|
| 4617 | the use of <b>CVS</b>. Nevertheless, one may advertize some well |
---|
| 4618 | tested conventions and practices which turned out to ensure a good |
---|
| 4619 | level of consistency between the two utilities.</p> |
---|
| 4620 | |
---|
| 4621 | <p>Although none of these are required, the <b>cmt</b> general |
---|
| 4622 | command provides a few utilities so as to simplify the use of these |
---|
| 4623 | practices. It should be noted that the added features provided by |
---|
| 4624 | cmt rely on the possibility to <i>query</i> CVS about the existing |
---|
| 4625 | <b>CMT</b> packages and the possible tags setup for these |
---|
| 4626 | packages. CVS does not by default permit such query operations |
---|
| 4627 | (since they require to scan the physical CVS repository). Therefore |
---|
| 4628 | <b>CMT</b> provides a hook to CVS (based upon standard CVS features |
---|
| 4629 | - not patches) for this. This hook can be installed following a |
---|
| 4630 | recipe explained in the dedicated |
---|
| 4631 | <a href="#The internal mechanism of cmt cvs operations">appendix</a>.</p> |
---|
| 4632 | |
---|
| 4633 | <cmt:section title="Importing a package into a cvs repository"> |
---|
| 4634 | |
---|
| 4635 | <p>Generally, everything composing a package (below the |
---|
| 4636 | <i>version</i> directory and besides the <i>binary</i> |
---|
| 4637 | directories) is relevant to be imported. Then choosing a |
---|
| 4638 | <b>cvs</b> <i>module</i> name is generally done on the basis of |
---|
| 4639 | the package name. Taking the previous examples, one could import |
---|
| 4640 | the <b>Foo</b> package as follows :</p> |
---|
| 4641 | |
---|
| 4642 | <cmt:code> |
---|
| 4643 | csh> cd ...../Foo/v1 |
---|
| 4644 | csh> cvs import -m "First import" -I alpha -I hp9000s700 Foo LAL v1 |
---|
| 4645 | </cmt:code> |
---|
| 4646 | |
---|
| 4647 | <p>In this example, </p> |
---|
| 4648 | |
---|
| 4649 | <ul> |
---|
| 4650 | <li> |
---|
| 4651 | we have ignored the currently existing binary directories |
---|
| 4652 | (here <b>alpha</b> and <b>hp9000s700</b>) |
---|
| 4653 | </li> |
---|
| 4654 | <li> |
---|
| 4655 | the <b>cvs</b> module name is identical to the package |
---|
| 4656 | name (<b>Foo</b>) |
---|
| 4657 | </li> |
---|
| 4658 | <li> |
---|
| 4659 | the original symbolic insertion tag is identical to the |
---|
| 4660 | version identifier (<b>v1</b>) |
---|
| 4661 | </li> |
---|
| 4662 | </ul> |
---|
| 4663 | |
---|
| 4664 | <p>The choice of the module name can generally be identical to the |
---|
| 4665 | package name. However, some site specific management issues may |
---|
| 4666 | lead to different choices (typically, a top directory where groups |
---|
| 4667 | of packages are gathered may be inserted).</p> |
---|
| 4668 | |
---|
| 4669 | <p>Conversely, using symbolic tags identical to version |
---|
| 4670 | identifiers appears to be a very good practice. The only |
---|
| 4671 | constraint induced by <b>cvs</b> is that the symbolic tags may not |
---|
| 4672 | contain <i>dot</i> characters (<b>'.'</b>), whereas no restriction |
---|
| 4673 | exist from <b>CMT</b> itself. Thus version identifiers like |
---|
| 4674 | <b>v3r2</b> will be preferred to the <b>v3.2</b> form. </p> |
---|
| 4675 | |
---|
| 4676 | </cmt:section> |
---|
| 4677 | |
---|
| 4678 | <cmt:section title="Checking a package out from a cvs repository"> |
---|
| 4679 | |
---|
| 4680 | <p>Assuming the previous conventions on module name and version |
---|
| 4681 | identifier have been selected when importing a package, the |
---|
| 4682 | following operations will naturally intervene when one need to |
---|
| 4683 | check a package out (typically to work on it or to install it on |
---|
| 4684 | some platform) : </p> |
---|
| 4685 | |
---|
| 4686 | <cmt:code> |
---|
| 4687 | csh> cd <some root> (1) |
---|
| 4688 | csh> mkdir Foo (2) |
---|
| 4689 | csh> cd Foo |
---|
| 4690 | csh> cvs checkout -d v1 Foo (3) |
---|
| 4691 | csh> cd v1/cmt |
---|
| 4692 | csh> cmt config (4) |
---|
| 4693 | csh> source setup.csh (5) |
---|
| 4694 | csh> [g]make (6) |
---|
| 4695 | </cmt:code> |
---|
| 4696 | |
---|
| 4697 | <ol> |
---|
| 4698 | <li> |
---|
| 4699 | one always have to select a root directory where to settle |
---|
| 4700 | down this copy of the extracted package. This may either be |
---|
| 4701 | the so-called <i>default root</i> or any other appropriate |
---|
| 4702 | directory. In both cases, the next <b>cmt config</b> |
---|
| 4703 | operation will automatically take care of this effective |
---|
| 4704 | location. |
---|
| 4705 | </li> |
---|
| 4706 | <li> |
---|
| 4707 | creating a base directory with the package name is mandatory |
---|
| 4708 | here, and is <i>not</i> taken into account by <b>cvs</b> |
---|
| 4709 | during the <i>chaeckout</i> operation since one wants to |
---|
| 4710 | insert the <i>version</i> branch in between. |
---|
| 4711 | </li> |
---|
| 4712 | <li> |
---|
| 4713 | the package is checked out into a directory named with the |
---|
| 4714 | expected version identifier exactly corresponding to the |
---|
| 4715 | version currently stored in the <b>cvs</b> |
---|
| 4716 | repository. |
---|
| 4717 | </li> |
---|
| 4718 | <li> |
---|
| 4719 | then using the <b>cmt config</b> command (from the |
---|
| 4720 | <b>cmt</b> branch) will update the setup scripts against |
---|
| 4721 | the <b><a HREF="#The requirements file">requirements</a></b> file and the effective current |
---|
| 4722 | package location. |
---|
| 4723 | </li> |
---|
| 4724 | <li> |
---|
| 4725 | using this updated version of the setup script provides the |
---|
| 4726 | appropriate set of environment variables |
---|
| 4727 | </li> |
---|
| 4728 | <li> lastly, rebuilding the entire package is possible simply |
---|
| 4729 | using the <b>[g]make</b> command. |
---|
| 4730 | </li> |
---|
| 4731 | |
---|
| 4732 | </ol> |
---|
| 4733 | |
---|
| 4734 | |
---|
| 4735 | <p>The actions decribed just above (from number 2 to number 4 |
---|
| 4736 | included) can also be performed using the <b>cmt checkout</b> |
---|
| 4737 | command. </p> |
---|
| 4738 | |
---|
| 4739 | <cmt:code> |
---|
| 4740 | > cd <some work area> |
---|
| 4741 | > cmt checkout [modifier ...] <package> ... |
---|
| 4742 | <i><font face="courier new, courier" COLOR="#007700"> |
---|
| 4743 | modifier : |
---|
| 4744 | -l Do not process used packages (default). |
---|
| 4745 | -R Process used packages recursively. |
---|
| 4746 | -r rev Check out version tag. (is sticky) |
---|
| 4747 | -d dir Check out into dir instead of module name. |
---|
| 4748 | -o offset Offset in the CVS repository |
---|
| 4749 | -n Simulation mode on |
---|
| 4750 | -v Verbose mode on |
---|
| 4751 | -help Print this help</font></i> |
---|
| 4752 | </cmt:code> |
---|
| 4753 | |
---|
| 4754 | Thus the previous example would become: |
---|
| 4755 | |
---|
| 4756 | <cmt:code> |
---|
| 4757 | csh> cd <some root> |
---|
| 4758 | csh> cmt checkout Foo |
---|
| 4759 | csh> cd Foo/v1/cmt |
---|
| 4760 | csh> source setup.csh |
---|
| 4761 | csh> [g]make |
---|
| 4762 | </cmt:code> |
---|
| 4763 | |
---|
| 4764 | </cmt:section> |
---|
| 4765 | |
---|
| 4766 | <cmt:section title="Querying CVS about some important infos"> |
---|
| 4767 | |
---|
| 4768 | It is possible, using the commands : |
---|
| 4769 | |
---|
| 4770 | <ul> |
---|
| 4771 | <li> |
---|
| 4772 | <b>cmt cvstags <module></b> |
---|
| 4773 | </li> |
---|
| 4774 | <li> |
---|
| 4775 | <b>cmt cvsbranches <module></b> |
---|
| 4776 | </li> |
---|
| 4777 | <li> |
---|
| 4778 | <b>cmt cvssubpackages <module></b> |
---|
| 4779 | </li> |
---|
| 4780 | </ul> |
---|
| 4781 | |
---|
| 4782 | <p> to query the <b>CVS</b> repository about the existing tags |
---|
| 4783 | installed onto a given <b>CVS</b> module, the subdirectories and |
---|
| 4784 | the subpackages (in the <b>CMT</b> meaning, i.e. when a <b><a |
---|
| 4785 | HREF="#The requirements file">requirements</a></b> file |
---|
| 4786 | exists). </p> |
---|
| 4787 | |
---|
| 4788 | <cmt:code> |
---|
| 4789 | > cmt cvstags Cm |
---|
| 4790 | <i><font face="courier new, courier" COLOR="#007700">v7r6 v7r5 v7r4 v7r3 v7r1 v7 </font></i> |
---|
| 4791 | > cmt cvstags Co |
---|
| 4792 | <i><font face="courier new, courier" COLOR="#007700">v3r7 v3r6 v3 </font></i> |
---|
| 4793 | </cmt:code> |
---|
| 4794 | |
---|
| 4795 | <p>One should notice here that the <b>cvstags</b> command can give |
---|
| 4796 | informations about any type of module, even if it is not managed |
---|
| 4797 | in the <b>CMT</b> environment. </p> |
---|
| 4798 | |
---|
| 4799 | <p>However, in order to let this mechanism operate, it is required |
---|
| 4800 | to install some elements into the physical <b>CVS</b> repository |
---|
| 4801 | (<i> which may require some access rights into it</i>). This |
---|
| 4802 | installation procedure (to be done only once in the life of the |
---|
| 4803 | repositiory) can be achieved through the following command:</p> |
---|
| 4804 | |
---|
| 4805 | <cmt:code> |
---|
| 4806 | sh> (cd ${CMTROOT}/mgr; gmake installcvs) |
---|
| 4807 | </cmt:code> |
---|
| 4808 | |
---|
| 4809 | <p>However, the details of the procedure is listed below (this |
---|
| 4810 | section is preferably reserved for system managers and can easily |
---|
| 4811 | be skipped by standard users):</p> |
---|
| 4812 | |
---|
| 4813 | <ol> |
---|
| 4814 | |
---|
| 4815 | <li> copy the <b>cmt_buildcvsinfos2.sh</b> shell script into the |
---|
| 4816 | management directory <b>${CVSROOT}/CVSROOT</b> as follows : |
---|
| 4817 | |
---|
| 4818 | <cmt:code> |
---|
| 4819 | sh> cp ${CMTROOT}/mgr/cmt_buildcvsinfos2.sh ${CVSROOT}/CVSROOT |
---|
| 4820 | </cmt:code> |
---|
| 4821 | </li> |
---|
| 4822 | |
---|
| 4823 | <li> install one special statement in the <b>loginfo</b> |
---|
| 4824 | administrative file as follows : |
---|
| 4825 | |
---|
| 4826 | <cmt:code> |
---|
| 4827 | sh> cd ... |
---|
| 4828 | sh> cvs checkout CVSROOT |
---|
| 4829 | sh> cd CVSROOT |
---|
| 4830 | sh> vi loginfo |
---|
| 4831 | ... |
---|
| 4832 | .cmtcvsinfos $CVSROOT/CVSROOT/cmt_buildcvsinfos2.sh |
---|
| 4833 | sh> cvs commit -m "set up commitinfo for CMT" |
---|
| 4834 | </cmt:code> |
---|
| 4835 | </li> |
---|
| 4836 | </ol> |
---|
| 4837 | |
---|
| 4838 | </cmt:section> |
---|
| 4839 | |
---|
| 4840 | <cmt:section title="Working on a package, creating a new release"> |
---|
| 4841 | |
---|
| 4842 | <p>This section presents the way to instanciate a new release of |
---|
| 4843 | a given package, which happens when the foreseen modifications |
---|
| 4844 | will yield additions or changes to the application programming |
---|
| 4845 | interface of the package. </p> |
---|
| 4846 | |
---|
| 4847 | <p>Then the version tag is supposed to be moved forward, either |
---|
| 4848 | increasing its minor identifier (in case of simple additions) or |
---|
| 4849 | its major identifier (in case of changes). </p> |
---|
| 4850 | |
---|
| 4851 | <p>The following actions should be undertaken then : </p> |
---|
| 4852 | |
---|
| 4853 | <ol> |
---|
| 4854 | <li> |
---|
| 4855 | understand what is the latest version tag (typically by |
---|
| 4856 | using the <b>cmt cvstags</b> command). Let's call it |
---|
| 4857 | <b>old-tag</b>. |
---|
| 4858 | <p></p> |
---|
| 4859 | </li> |
---|
| 4860 | <li> |
---|
| 4861 | select (according to the foreseen amount of changes) what |
---|
| 4862 | will be the next version tag. Let's call it |
---|
| 4863 | <b>new-tag</b>. |
---|
| 4864 | <p></p> |
---|
| 4865 | </li> |
---|
| 4866 | <li> |
---|
| 4867 | check the most recent version of the package in your |
---|
| 4868 | development area : |
---|
| 4869 | |
---|
| 4870 | <cmt:code> |
---|
| 4871 | sh> cd <development area> |
---|
| 4872 | sh> cvs checkout -d <new-tag> <package> |
---|
| 4873 | </cmt:code> |
---|
| 4874 | </li> |
---|
| 4875 | <li> |
---|
| 4876 | configure this new release, and rebuild it : |
---|
| 4877 | |
---|
| 4878 | <cmt:code> |
---|
| 4879 | sh> cd <new-tag>/cmt |
---|
| 4880 | sh> cmt config |
---|
| 4881 | sh> source setup.csh |
---|
| 4882 | sh> [g]make |
---|
| 4883 | </cmt:code> |
---|
| 4884 | </li> |
---|
| 4885 | </ol> |
---|
| 4886 | |
---|
| 4887 | </cmt:section> |
---|
| 4888 | <cmt:section title="Getting a particular tagged version out of CVS"> |
---|
| 4889 | |
---|
| 4890 | <p>The previous example presented the standard case where one gets |
---|
| 4891 | the <i>most recent</i> version of a given package. The procedure |
---|
| 4892 | is only slightly modified when one wants to extract a previously |
---|
| 4893 | tagged version. Let's imagine that the <b>Foo</b> package has |
---|
| 4894 | evolved by several iterations, leading to several tagged |
---|
| 4895 | releases in the <b>cvs</b> repository (say <b>v2</b> and |
---|
| 4896 | <b>v3</b>). If the <b>v2</b> release is to be used (e.g. for |
---|
| 4897 | understanding and fixing a problem discovered in the running |
---|
| 4898 | version) one will operate as follows :</p> |
---|
| 4899 | |
---|
| 4900 | <cmt:code> |
---|
| 4901 | csh> cd <some root> |
---|
| 4902 | csh> mkdir Foo |
---|
| 4903 | csh> cd Foo |
---|
| 4904 | csh> cvs checkout -d v2 -r v2 Foo |
---|
| 4905 | csh> cd v2/cmt |
---|
| 4906 | csh> cmt config |
---|
| 4907 | csh> source setup.csh |
---|
| 4908 | csh> make |
---|
| 4909 | </cmt:code> |
---|
| 4910 | </cmt:section> |
---|
| 4911 | </cmt:section> |
---|
| 4912 | |
---|
| 4913 | <cmt:section title="Interfacing an external package with CMT"> |
---|
| 4914 | |
---|
| 4915 | <p>Very often, external packages (typically commercial products, or |
---|
| 4916 | third party software) are to be used by packages developped in the |
---|
| 4917 | context of the <b>CMT</b> environment. Although this can obviously |
---|
| 4918 | done simply by specifying compiler or linker options internally to |
---|
| 4919 | the client packages, it can be quite powerful to interface these |
---|
| 4920 | so-called <i>external</i> packages to <b>CMT</b> by defining a |
---|
| 4921 | <i>glue</i> package, where configuration specifications for this |
---|
| 4922 | external package are detailed.</p> |
---|
| 4923 | |
---|
| 4924 | <p>Using this approach, one may : </p> |
---|
| 4925 | |
---|
| 4926 | <ul> |
---|
| 4927 | <li> |
---|
| 4928 | provide a <i>nickname</i> for this external package, |
---|
| 4929 | </li> |
---|
| 4930 | <li> |
---|
| 4931 | adapt the version tag convention consistently to the |
---|
| 4932 | project, hiding the version tag specificities of |
---|
| 4933 | eg. commercial packages. |
---|
| 4934 | </li> |
---|
| 4935 | <li> |
---|
| 4936 | provide compiler options using the the standard make macros |
---|
| 4937 | <b><package>_cflags</b>, <b><package>_cppflags</b> |
---|
| 4938 | or <b><package>_fflags</b>, |
---|
| 4939 | </li> |
---|
| 4940 | <li> |
---|
| 4941 | specify a set of search paths for the include files, using |
---|
| 4942 | the <b>include_dirs</b> statement, |
---|
| 4943 | </li> |
---|
| 4944 | <li> |
---|
| 4945 | provide linker options using the the standard make macros |
---|
| 4946 | <b><package>_linkopts</b> |
---|
| 4947 | </li> |
---|
| 4948 | </ul> |
---|
| 4949 | |
---|
| 4950 | Let's consider the example of the <b>OPACS</b> package. This |
---|
| 4951 | package is provided outside of the <b>CMT</b> |
---|
| 4952 | environment. Providing a directory tree following the |
---|
| 4953 | <b>CMT</b> conventions (ie. a branch named after the version |
---|
| 4954 | identifier, then an <b>cmt</b> branch) then a |
---|
| 4955 | <b>&CMTrequirements;</b> file, containing (among other statements |
---|
| 4956 | not shown for the sake of clarity) : |
---|
| 4957 | |
---|
| 4958 | <cmt:code> |
---|
| 4959 | package OPACS |
---|
| 4960 | |
---|
| 4961 | include_dirs ${Wo_root}/include ${Co_root}/include ${Xx_root}/include \ |
---|
| 4962 | ${Ho_root}/include ${Go_root}/include ${Xo_root}/include |
---|
| 4963 | |
---|
| 4964 | public |
---|
| 4965 | macro OPACS_cflags "-DHAS_XO -DHAS_XM" |
---|
| 4966 | macro OPACS_cppflags " $(OPACS_cflags) " |
---|
| 4967 | |
---|
| 4968 | macro OPACS_linkopts "$(Wo_linkopts) $(Xo_linkopts) $(Go_linkopts) \ |
---|
| 4969 | $(Glo_linkopts) $(Xx_linkopts) $(Ho_linkopts) $(Htmlo_linkopts) \ |
---|
| 4970 | $(W3o_linkopts) $(Co_linkopts) $(X_linkopts)" |
---|
| 4971 | </cmt:code> |
---|
| 4972 | |
---|
| 4973 | <p>Then every package or application, client of this |
---|
| 4974 | <b>OPACS</b> package would have just to provide a use |
---|
| 4975 | statement like : </p> |
---|
| 4976 | |
---|
| 4977 | <cmt:code> |
---|
| 4978 | use OPACS v3 |
---|
| 4979 | </cmt:code> |
---|
| 4980 | |
---|
| 4981 | <p>This procedure gives the complete benefit of the use |
---|
| 4982 | relationships between packages (a client application |
---|
| 4983 | transparently inherits all configuration specifications) while |
---|
| 4984 | keeping unchanged the original referenced package, allowing to |
---|
| 4985 | apply this approach even to commercial products so that they |
---|
| 4986 | may be integrated in resource usage surveys similarly to local |
---|
| 4987 | packages. </p> |
---|
| 4988 | |
---|
| 4989 | </cmt:section> |
---|
| 4990 | |
---|
| 4991 | <cmt:section title="The installation area mechanism"> |
---|
| 4992 | |
---|
| 4993 | <p>CMT proposes and implements a flexible architecture for |
---|
| 4994 | installation areas, meant to group the results of the build process |
---|
| 4995 | or any other information belonging to packages into shared disk |
---|
| 4996 | spaces. The typical usage of such installation areas is classical |
---|
| 4997 | and expect to make only visible to the clients of a given |
---|
| 4998 | (sub-)project the results of the build process while hiding the |
---|
| 4999 | details of the package sources.</p> |
---|
| 5000 | |
---|
| 5001 | <p>the basics of the mechanisms supported by CMT are the following:</p> |
---|
| 5002 | |
---|
| 5003 | <ol> |
---|
| 5004 | |
---|
| 5005 | <li><p></p>All mechanisms are customizable, so as to easily follow the |
---|
| 5006 | project specific conventions</li> |
---|
| 5007 | |
---|
| 5008 | <li><p></p>However CMT proposes a minimal default behaviour based on the |
---|
| 5009 | concrete experience in large projects, as well as frequently met |
---|
| 5010 | practices</li> |
---|
| 5011 | |
---|
| 5012 | <li><p></p>A typical well supported convention is to map the set of |
---|
| 5013 | installation areas onto the set of CMTPATH entries, associating the |
---|
| 5014 | concept of CMTPATH splitting with the sub-project |
---|
| 5015 | organization</li> |
---|
| 5016 | |
---|
| 5017 | <li><p></p>A typical consequence of this approach is that many |
---|
| 5018 | configuration parameters need to be set according to the list of |
---|
| 5019 | CMTPATH items. Eg on a Unix system, if one expects to find shared |
---|
| 5020 | libraries in every installation area, each of them being created |
---|
| 5021 | in a corresponding CMTPATH entry, one also expects to have |
---|
| 5022 | LD_LIBRARY_PATH entries accordingly. The mechanism of |
---|
| 5023 | cmtpath_pattern is exactly designed for that.</li> |
---|
| 5024 | |
---|
| 5025 | <li><p></p>The mechanism easily supports the extension for installing |
---|
| 5026 | binary files (libraries, applications, java classes), runtime |
---|
| 5027 | files, documentation and header files.</li> |
---|
| 5028 | |
---|
| 5029 | </ol> |
---|
| 5030 | |
---|
| 5031 | <cmt:section title="The default implementation"> |
---|
| 5032 | |
---|
| 5033 | <p>It is provided in terms of</p> |
---|
| 5034 | |
---|
| 5035 | <ol> |
---|
| 5036 | |
---|
| 5037 | <li> |
---|
| 5038 | |
---|
| 5039 | <p></p> |
---|
| 5040 | A set of cmtpath_patterns defined in the CMT requirements |
---|
| 5041 | file. This can be displayed using the command |
---|
| 5042 | |
---|
| 5043 | <cmt:code> |
---|
| 5044 | > cmt show cmtpath_patterns |
---|
| 5045 | </cmt:code> |
---|
| 5046 | |
---|
| 5047 | </li> |
---|
| 5048 | |
---|
| 5049 | <li> |
---|
| 5050 | |
---|
| 5051 | <p></p> |
---|
| 5052 | A consistent set of actions added to the following make_fragments |
---|
| 5053 | |
---|
| 5054 | <table> |
---|
| 5055 | <tr><td>application</td><td>applications</td></tr> |
---|
| 5056 | <tr><td>library</td><td>shared libraries</td></tr> |
---|
| 5057 | <tr><td>library_no_share</td><td>static libraries</td></tr> |
---|
| 5058 | <tr><td>java_header</td><td>Java applications</td></tr> |
---|
| 5059 | <tr><td>jar</td><td>Java libraries</td></tr> |
---|
| 5060 | </table> |
---|
| 5061 | |
---|
| 5062 | </li> |
---|
| 5063 | |
---|
| 5064 | <li> |
---|
| 5065 | <p></p> |
---|
| 5066 | <p>One shell script for installing or uninstalling files or directories</p> |
---|
| 5067 | |
---|
| 5068 | <cmt:code> |
---|
| 5069 | ${CMTROOT}/mgr/cmt_install_action.sh |
---|
| 5070 | ${CMTROOT}/mgr/cmt_uninstall_action.sh |
---|
| 5071 | ${CMTROOT}/mgr/cmt_install_action.bat |
---|
| 5072 | ${CMTROOT}/mgr/cmt_uninstall_action.bat |
---|
| 5073 | </cmt:code> |
---|
| 5074 | |
---|
| 5075 | </li> |
---|
| 5076 | |
---|
| 5077 | <p>The default architecture of this installation scheme is by |
---|
| 5078 | default set for each CMTPATH entry to:</p> |
---|
| 5079 | |
---|
| 5080 | <cmt:code> |
---|
| 5081 | <path>/InstallationArea/$(tag)/bin/... [1] |
---|
| 5082 | /$(tag)/lib/... [2] |
---|
| 5083 | /include/<package>/... [3] |
---|
| 5084 | /share/bin/... [4] |
---|
| 5085 | /share/lib/... [5] |
---|
| 5086 | /... [6] |
---|
| 5087 | /doc/<package>/... [7] |
---|
| 5088 | /... [8] |
---|
| 5089 | </cmt:code> |
---|
| 5090 | |
---|
| 5091 | <ol> |
---|
| 5092 | <li>Platform dependent executables</li> |
---|
| 5093 | <li>Platform dependent libraries</li> |
---|
| 5094 | <li>Public header files </li> |
---|
| 5095 | <li>Platform independent applications (eg Java applications)</li> |
---|
| 5096 | <li>Platform independent libraries (eg Java libraries)</li> |
---|
| 5097 | <li>other platform independent files</li> |
---|
| 5098 | <li>package specific documentations</li> |
---|
| 5099 | <li>project-wide documentation</li> |
---|
| 5100 | </ol> |
---|
| 5101 | |
---|
| 5102 | </ol> |
---|
| 5103 | |
---|
| 5104 | <p>The cmtpath_patterns are designed in this implementation for |
---|
| 5105 | constructing a proper and consistent sequence of system specific |
---|
| 5106 | environment variables (eg PATH, LD_LIBRARY_PATH, CLASSPATH) as |
---|
| 5107 | well as compiler or linker options so as to transparently refer to |
---|
| 5108 | the installation area only when it is appropriate to ovverride the |
---|
| 5109 | local patterns.</p> |
---|
| 5110 | |
---|
| 5111 | </cmt:section> |
---|
| 5112 | |
---|
| 5113 | </cmt:section> |
---|
| 5114 | |
---|
| 5115 | <cmt:section title="Installing CMT for the first time"> |
---|
| 5116 | |
---|
| 5117 | <P>These sections are of interest only if <b>CMT</b> is not yet |
---|
| 5118 | installed on your site, of if you need a private |
---|
| 5119 | installation. </P> |
---|
| 5120 | |
---|
| 5121 | <P>The first question you need to answer is the location where |
---|
| 5122 | to install <b>CMT</b>. This location is typically a disk area where |
---|
| 5123 | most of packages managed in your project will be located. </P> |
---|
| 5124 | |
---|
| 5125 | <P>Then, you have to fetch the distribution kit from the Web at |
---|
| 5126 | <A HREF="http://www.lal.in2p3.fr/SI/CMT">http://www.lal.in2p3.fr/SI/CMT</A>. You |
---|
| 5127 | must get at least the primary distribution kit containing the |
---|
| 5128 | basic configuration information and the <b>CMT</b> sources. This |
---|
| 5129 | operation results in a set of directories hanging below the <b>CMT</b> |
---|
| 5130 | root and the version directory. The src branch contains the |
---|
| 5131 | sources of <b>CMT</b>, the fragments branch contains the makefile |
---|
| 5132 | fragments and the mgr branch contains the scripts needed to build |
---|
| 5133 | or operate <b>CMT</b>. </P> |
---|
| 5134 | |
---|
| 5135 | <cmt:section title="Installing CMT on your Unix site"> |
---|
| 5136 | |
---|
| 5137 | <P>The very first operation after dowloading <b>CMT</b> consists in |
---|
| 5138 | running the INSTALL shell script. This will build the setup |
---|
| 5139 | scripts required by any <b>CMT</b> user. </P> |
---|
| 5140 | |
---|
| 5141 | <P>Then you may either decide to build <b>CMT</b> by yourself or fetch |
---|
| 5142 | a pre-built binary from the same Web location. The prebuilt |
---|
| 5143 | binary versions may not exist for the actual platform you are |
---|
| 5144 | working on. You will see on the distribution page the precise |
---|
| 5145 | configurations used for building those binaries. </P> |
---|
| 5146 | |
---|
| 5147 | <P>In case you have to build <b>CMT</b> yourself, you need a C++ |
---|
| 5148 | compiler capable of handling templates (although the support for |
---|
| 5149 | STL is not required). There is a Makefile provided in the |
---|
| 5150 | distribution kit which takes g++ by default as the compiler. If |
---|
| 5151 | you need a specific C++ compiler you will override the cpp macro |
---|
| 5152 | as follows: </P> |
---|
| 5153 | |
---|
| 5154 | <cmt:code> |
---|
| 5155 | sh> gmake cpp=CC |
---|
| 5156 | </cmt:code> |
---|
| 5157 | |
---|
| 5158 | <P>The <b>cppflags</b> macro can also be used to override the |
---|
| 5159 | behaviour of the compilation. </P> |
---|
| 5160 | |
---|
| 5161 | <P>Another important concern is the way <b>CMT</b> will identify the |
---|
| 5162 | platform. <b>CMT</b> builds a configuration tag per each type of |
---|
| 5163 | platform, and uses this tag for naming the directory where all |
---|
| 5164 | binary files will be stored. As such this tag has to be defined |
---|
| 5165 | prior to even build <b>CMT</b> itself. </P> |
---|
| 5166 | |
---|
| 5167 | <P><b>CMT</b> builds the default configuration by running the |
---|
| 5168 | cmt_system.sh script found in the mgr branch of <b>CMT</b>. Run it |
---|
| 5169 | manually to see what is the default value provided by this |
---|
| 5170 | script. You might consider changing its algorithm for your own |
---|
| 5171 | convenience. </P> |
---|
| 5172 | |
---|
| 5173 | <p>A distribution kit may be obtained at the following URL : </p> |
---|
| 5174 | |
---|
| 5175 | <cmt:code> |
---|
| 5176 | http://www.cmtsite.org |
---|
| 5177 | </cmt:code> |
---|
| 5178 | |
---|
| 5179 | <p>Once the <b>tar</b> file has been downloaded, the |
---|
| 5180 | following operations must be achieved : </p> |
---|
| 5181 | |
---|
| 5182 | <ol> |
---|
| 5183 | <li> |
---|
| 5184 | Select a root directory where to install |
---|
| 5185 | <b>CMT</b>. Typically this will correspond to a |
---|
| 5186 | development area or a public distribution area. |
---|
| 5187 | </li> |
---|
| 5188 | <li> |
---|
| 5189 | Import the distribution kit mentioned above. |
---|
| 5190 | </li> |
---|
| 5191 | <li> |
---|
| 5192 | Uncompress and untar it. |
---|
| 5193 | </li> |
---|
| 5194 | <li> |
---|
| 5195 | Configure <b>CMT</b>. |
---|
| 5196 | </li> |
---|
| 5197 | <li> |
---|
| 5198 | CMT is ready to be used for developing packages. |
---|
| 5199 | </li> |
---|
| 5200 | </ol> |
---|
| 5201 | |
---|
| 5202 | <p>A typical corresponding session could look like : </p> |
---|
| 5203 | |
---|
| 5204 | <cmt:code> |
---|
| 5205 | csh> cd /Packages |
---|
| 5206 | csh> <get the tar file from the Web> |
---|
| 5207 | csh> tar xzf CMT&CMTVersion;.tar.gz |
---|
| 5208 | csh> cd CMT/&CMTVersion;/mgr |
---|
| 5209 | csh> ./INSTALL |
---|
| 5210 | csh> source setup.csh |
---|
| 5211 | csh> gmake |
---|
| 5212 | </cmt:code> |
---|
| 5213 | |
---|
| 5214 | </cmt:section> |
---|
| 5215 | |
---|
| 5216 | <cmt:section title="Installing CMT on a Windows or Windows NT site"> |
---|
| 5217 | |
---|
| 5218 | <p>You first have to fetch the distribution kit from the Web at |
---|
| 5219 | <A |
---|
| 5220 | HREF="http://www.cmtsite.org">http://www.cmtsite.org</A>. You |
---|
| 5221 | must get at least the primary distribution kit containing the |
---|
| 5222 | basic configuration information and the <b>CMT</b> sources. This |
---|
| 5223 | operation results in a set of directories hanging below the <b>CMT</b> |
---|
| 5224 | root and the version directory. The binary kit provided for |
---|
| 5225 | Windows environments will generally fit your needs. </p> |
---|
| 5226 | |
---|
| 5227 | <p>You should consider getting the pre-compiled (for a Windows |
---|
| 5228 | environment) applications, and especially the |
---|
| 5229 | <b>..\VisualC\install.exe</b> application, which interactively |
---|
| 5230 | configures the registry entries as described in the |
---|
| 5231 | next paragraph.</p> |
---|
| 5232 | |
---|
| 5233 | <p>The next operation consists in defining a few registries |
---|
| 5234 | (typically using the standard RegEdit facility or the |
---|
| 5235 | <b>install.exe</b> special application): </p> |
---|
| 5236 | |
---|
| 5237 | <UL> |
---|
| 5238 | |
---|
| 5239 | <li>HKEY_LOCAL_MACHINE/Software/CMT/root will contain the root |
---|
| 5240 | directory where <b>CMT</b> is installed (eg. "e:"). </li> |
---|
| 5241 | |
---|
| 5242 | <li>HKEY_LOCAL_MACHINE/Software/CMT/version will contain the |
---|
| 5243 | current version tag of <b>CMT</b> ("&CMTVersion;" for this version). </li> |
---|
| 5244 | |
---|
| 5245 | <li>HKEY_LOCAL_MACHINE/Software/CMT/path/ may optionally |
---|
| 5246 | contain a set of text values corresponding to the different |
---|
| 5247 | package global access paths. </li> |
---|
| 5248 | |
---|
| 5249 | <li>HKEY_LOCAL_MACHINE/Software/CMT/site will contain the |
---|
| 5250 | conventional site name. </li> |
---|
| 5251 | |
---|
| 5252 | <li>HKEY_CURRENT_USER/Software/CMT/path/ may contain a set of |
---|
| 5253 | text of text values corresponding to the different package |
---|
| 5254 | private access paths. </li> |
---|
| 5255 | </UL> |
---|
| 5256 | |
---|
| 5257 | <p>CMT can also be configured to run on DOS-based environments |
---|
| 5258 | using the <b>nmake</b> facility. In this case, the installation |
---|
| 5259 | procedure is very similar to the Unix one:</p> |
---|
| 5260 | |
---|
| 5261 | <p>A typical corresponding session could look like : |
---|
| 5262 | |
---|
| 5263 | <cmt:code> |
---|
| 5264 | dos> cd Packages |
---|
| 5265 | dos> <get the tar file from the Web> |
---|
| 5266 | dos> cd CMT\&CMTVersion;\mgr |
---|
| 5267 | dos> call INSTALL |
---|
| 5268 | dos> call setup.bat |
---|
| 5269 | dos> nmake /f nmake |
---|
| 5270 | </cmt:code> |
---|
| 5271 | |
---|
| 5272 | </p> |
---|
| 5273 | |
---|
| 5274 | </cmt:section> |
---|
| 5275 | |
---|
| 5276 | </cmt:section> |
---|
| 5277 | |
---|
| 5278 | <cmt:section title="Differences with previous versions"> |
---|
| 5279 | |
---|
| 5280 | </cmt:section> |
---|
| 5281 | |
---|
| 5282 | <cmt:section title="Appendices"> |
---|
| 5283 | |
---|
| 5284 | <cmt:section title='Copyright'> |
---|
| 5285 | |
---|
| 5286 | <center> |
---|
| 5287 | Copyright (c) 1996 LAL Orsay, UPS-IN2P3-CNRS (France). |
---|
| 5288 | </center> |
---|
| 5289 | |
---|
| 5290 | Redistribution and use in source and binary forms, with or |
---|
| 5291 | without modification, are permitted provided that the following |
---|
| 5292 | conditions are met: |
---|
| 5293 | |
---|
| 5294 | <ul> |
---|
| 5295 | <li> |
---|
| 5296 | Redistributions of source code must retain the above |
---|
| 5297 | copyright notice, this list of conditions and the following |
---|
| 5298 | disclaimer. |
---|
| 5299 | </li> |
---|
| 5300 | <li> |
---|
| 5301 | Redistributions in binary form must reproduce the above |
---|
| 5302 | copyright notice, this list of conditions and the following |
---|
| 5303 | disclaimer in the documentation and/or other materials |
---|
| 5304 | provided with the distribution. |
---|
| 5305 | </li> |
---|
| 5306 | <li> |
---|
| 5307 | All advertising materials mentioning features or use of this |
---|
| 5308 | software must display the following acknowledgement: |
---|
| 5309 | </li> |
---|
| 5310 | </ul> |
---|
| 5311 | |
---|
| 5312 | <center> |
---|
| 5313 | <font face="Courier New,Courier" COLOR="#770077"> |
---|
| 5314 | This product includes |
---|
| 5315 | software developed by the <br/>Computer Application Development |
---|
| 5316 | Group at LAL Orsay <br/>(Laboratoire de l'Accelerateur Linaire - |
---|
| 5317 | UPS-IN2P3-CNRS). |
---|
| 5318 | </font> |
---|
| 5319 | </center> |
---|
| 5320 | |
---|
| 5321 | <ul> |
---|
| 5322 | <li> |
---|
| 5323 | Neither the name of the Institute nor of the Laboratory may |
---|
| 5324 | be used to endorse or promote products derived from this |
---|
| 5325 | software without specific prior written permission. |
---|
| 5326 | </li> |
---|
| 5327 | </ul> |
---|
| 5328 | |
---|
| 5329 | <b>This software is provided by the LAL and contributors ``as |
---|
| 5330 | is'' and any express or implied warranties, including, but not |
---|
| 5331 | limited to, the implied warranties of merchantability and |
---|
| 5332 | fitness for a particular purpose are disclaimed. In no |
---|
| 5333 | event shall the LAL or contributors be liable for any direct, |
---|
| 5334 | indirect, incidental, special, exemplary, or consequential |
---|
| 5335 | damages (including, but not limited to, procurement of |
---|
| 5336 | substitute goods or services; loss of use, data, or profits; or |
---|
| 5337 | business interruption) however caused and on any theory of |
---|
| 5338 | liability, whether in contract, strict liability, or tort |
---|
| 5339 | (including negligence or otherwise) arising in any way out of |
---|
| 5340 | the use of this software, even if advised of the possibility of |
---|
| 5341 | such damage.</b> |
---|
| 5342 | </cmt:section> |
---|
| 5343 | |
---|
| 5344 | <cmt:section title="Standard make targets predefined in CMT"> |
---|
| 5345 | |
---|
| 5346 | <p>These targets can always be listed through the following command : </p> |
---|
| 5347 | |
---|
| 5348 | <cmt:code> |
---|
| 5349 | sh> gmake help |
---|
| 5350 | </cmt:code> |
---|
| 5351 | |
---|
| 5352 | <p> |
---|
| 5353 | <table BORDER='1' COLS='2'> |
---|
| 5354 | <tr> |
---|
| 5355 | <td width="200"> |
---|
| 5356 | <center><i>target</i></center> |
---|
| 5357 | </td> |
---|
| 5358 | <td width="500"> |
---|
| 5359 | <center><i>usage</i></center> |
---|
| 5360 | </td> |
---|
| 5361 | </tr> |
---|
| 5362 | |
---|
| 5363 | <tr> |
---|
| 5364 | <td><b>help</b></td> |
---|
| 5365 | <td >Get the list of possible make target for this package.</td> |
---|
| 5366 | </tr> |
---|
| 5367 | |
---|
| 5368 | <tr> |
---|
| 5369 | <td><b>all</b></td> |
---|
| 5370 | <td >build all components of this package.</td> |
---|
| 5371 | </tr> |
---|
| 5372 | |
---|
| 5373 | <tr> |
---|
| 5374 | <td><b>clean</b></td> |
---|
| 5375 | <td>remove everything that can be rebuilt by make</td> |
---|
| 5376 | </tr> |
---|
| 5377 | |
---|
| 5378 | <tr> |
---|
| 5379 | <td><b>configclean</b></td> |
---|
| 5380 | <td>remove all intermediate makefile fragments</td> |
---|
| 5381 | </tr> |
---|
| 5382 | |
---|
| 5383 | <tr> |
---|
| 5384 | <td><b>install</b></td> |
---|
| 5385 | <td>install binaries of this package to the current installation area</td> |
---|
| 5386 | </tr> |
---|
| 5387 | |
---|
| 5388 | <tr> |
---|
| 5389 | <td><b>uninstall</b></td> |
---|
| 5390 | <td>uninstall binaries of this package from the current installation area</td> |
---|
| 5391 | </tr> |
---|
| 5392 | |
---|
| 5393 | <tr> |
---|
| 5394 | <td><b>check</b></td> |
---|
| 5395 | <td>run all applications defined with the -check option</td> |
---|
| 5396 | </tr> |
---|
| 5397 | |
---|
| 5398 | <tr> |
---|
| 5399 | <td><i>component-name</i></td> |
---|
| 5400 | <td>only build this |
---|
| 5401 | particular component (as opposed to the <b>all</b> |
---|
| 5402 | target that tries to build all components of this |
---|
| 5403 | package)</td> |
---|
| 5404 | </tr> |
---|
| 5405 | |
---|
| 5406 | <tr> |
---|
| 5407 | |
---|
| 5408 | <td><i>group-name</i> |
---|
| 5409 | </td> <td>build all constituents |
---|
| 5410 | belonging to this group (ie. those defined using the same |
---|
| 5411 | -group=<group-name> option)</td> |
---|
| 5412 | |
---|
| 5413 | </tr> |
---|
| 5414 | |
---|
| 5415 | </table> |
---|
| 5416 | </p> |
---|
| 5417 | |
---|
| 5418 | <p>These targets have to be specified as follows : </p> |
---|
| 5419 | |
---|
| 5420 | <cmt:code> |
---|
| 5421 | sh> gmake clean |
---|
| 5422 | sh> gmake Foo |
---|
| 5423 | </cmt:code> |
---|
| 5424 | |
---|
| 5425 | </cmt:section> |
---|
| 5426 | |
---|
| 5427 | |
---|
| 5428 | <cmt:section title="Standard macros predefined in CMT"> |
---|
| 5429 | |
---|
| 5430 | <cmt:section title="Structural macros"> |
---|
| 5431 | |
---|
| 5432 | These macros describe the structural conventions followed by |
---|
| 5433 | <b>CMT</b>. They receive a conventional default value from the <b>CMT</b> |
---|
| 5434 | requirements file. However, they can be overridden in any |
---|
| 5435 | package for its own needs. |
---|
| 5436 | |
---|
| 5437 | <p></p> |
---|
| 5438 | <center> |
---|
| 5439 | <table BORDER='1' COLS='3'> |
---|
| 5440 | <tr> |
---|
| 5441 | <td width="150"> |
---|
| 5442 | <center><i>macro</i></center> |
---|
| 5443 | </td> |
---|
| 5444 | <td width="300"> |
---|
| 5445 | <center><i>usage</i></center> |
---|
| 5446 | </td> |
---|
| 5447 | <td width="200"> |
---|
| 5448 | <center><i>default value</i></center> |
---|
| 5449 | </td> |
---|
| 5450 | </tr> |
---|
| 5451 | <tr> |
---|
| 5452 | <td><b>CMTrelease</b></td> |
---|
| 5453 | <td>gives the current release number of CMT</td> |
---|
| 5454 | <td><b>14</b></td> |
---|
| 5455 | </tr> |
---|
| 5456 | <tr> |
---|
| 5457 | <td><b>CMTVERSION</b></td> |
---|
| 5458 | <td>gives the current complete version tag of CMT</td> |
---|
| 5459 | <td><b>v1r14p20030811</b></td> |
---|
| 5460 | </tr> |
---|
| 5461 | <tr> |
---|
| 5462 | <td><b>tag</b></td> |
---|
| 5463 | <td>gives the binary tag</td> |
---|
| 5464 | <td><b>${CMTCONFIG}</b></td> |
---|
| 5465 | </tr> |
---|
| 5466 | <tr> |
---|
| 5467 | <td><b>src</b></td> |
---|
| 5468 | <td>the src branch</td> |
---|
| 5469 | <td><b>../src/</b></td> |
---|
| 5470 | </tr> |
---|
| 5471 | <tr> |
---|
| 5472 | <td><b>inc</b></td> |
---|
| 5473 | <td>the include branch</td> |
---|
| 5474 | <td><b>../src/</b></td> |
---|
| 5475 | </tr> |
---|
| 5476 | <tr> |
---|
| 5477 | <td><b>mgr</b></td> |
---|
| 5478 | <td>the cmt or mgr branch</td> |
---|
| 5479 | <td><b>../cmt/</b> or <b>../mgr/</b></td> |
---|
| 5480 | </tr> |
---|
| 5481 | <tr> |
---|
| 5482 | <td><b>bin</b></td> |
---|
| 5483 | <td>the branch for binaries</td> |
---|
| 5484 | <td><b>../$(<package>_tag)/</b></td> |
---|
| 5485 | </tr> |
---|
| 5486 | <tr> |
---|
| 5487 | <td><b>javabin</b></td> |
---|
| 5488 | <td>the branch for java classes</td> |
---|
| 5489 | <td><b>../classes/</b></td> |
---|
| 5490 | </tr> |
---|
| 5491 | <tr> |
---|
| 5492 | <td><b>doc</b></td> |
---|
| 5493 | <td>the doc branch</td> |
---|
| 5494 | <td><b>../doc/</b></td> |
---|
| 5495 | </tr> |
---|
| 5496 | <tr> |
---|
| 5497 | <td><b>cmt_hardware</b></td> |
---|
| 5498 | <td>the description of the current hardware</td> |
---|
| 5499 | <td><b><none></b></td> |
---|
| 5500 | </tr> |
---|
| 5501 | <tr> |
---|
| 5502 | <td><b>cmt_system_version</b></td> |
---|
| 5503 | <td>the version of the current OS</td> |
---|
| 5504 | <td><b><none></b></td> |
---|
| 5505 | </tr> |
---|
| 5506 | <tr> |
---|
| 5507 | <td><b>cmt_compiler_version</b></td> |
---|
| 5508 | <td>the version of the currently visible C++ compiler </td> |
---|
| 5509 | <td><b><none></b></td> |
---|
| 5510 | </tr> |
---|
| 5511 | </table> |
---|
| 5512 | </center> |
---|
| 5513 | |
---|
| 5514 | </cmt:section> |
---|
| 5515 | |
---|
| 5516 | <cmt:section title="Language related macros"> |
---|
| 5517 | |
---|
| 5518 | These macros are purely conventional. They are expected in the |
---|
| 5519 | various make fragments available from <b>CMT</b> itself for providing |
---|
| 5520 | the various building actions. |
---|
| 5521 | |
---|
| 5522 | <p>During the mechanism of new language declaration and |
---|
| 5523 | definition available in the <b>CMT</b> syntax, developers are |
---|
| 5524 | expected to define similar conventions for corresponding |
---|
| 5525 | actions.</p> |
---|
| 5526 | |
---|
| 5527 | <p> Their default values are originally defined inside the &CMTrequirements; file of the |
---|
| 5528 | <b>CMT</b> package itself but can be <i>redefined</i> by |
---|
| 5529 | providing a new definition in the package's requirements file |
---|
| 5530 | using the <b>macro</b> statement. The original definition |
---|
| 5531 | can be <i>completed</i> using the <b>macro_append</b> or |
---|
| 5532 | <b>macro_prepend</b> statements.</p> |
---|
| 5533 | |
---|
| 5534 | <p> |
---|
| 5535 | <table BORDER='1' COLS='3'> |
---|
| 5536 | <tr> |
---|
| 5537 | <td width="150"><b>cc</b></td> |
---|
| 5538 | <td width="300">The C compiler</td> |
---|
| 5539 | <td width="200"><b>cc</b></td> |
---|
| 5540 | </tr> |
---|
| 5541 | <tr> |
---|
| 5542 | <td><b>ccomp</b></td> |
---|
| 5543 | <td>The C compiling command</td> |
---|
| 5544 | <td><b>$(cc) -c -I$(inc) $(includes) $(cflags)</b></td> |
---|
| 5545 | </tr> |
---|
| 5546 | <tr> |
---|
| 5547 | <td><b>clink</b></td> |
---|
| 5548 | <td>The C linking command</td> |
---|
| 5549 | <td><b>$(cc) $(clinkflags)</b></td> |
---|
| 5550 | </tr> |
---|
| 5551 | <tr> |
---|
| 5552 | <td><b>cflags</b></td> |
---|
| 5553 | <td>The C compilation flags</td> |
---|
| 5554 | <td><i>none</i> </td> |
---|
| 5555 | </tr> |
---|
| 5556 | <tr> |
---|
| 5557 | <td><b>pp_cflags</b></td> |
---|
| 5558 | <td>The preprocessor flags for C</td> |
---|
| 5559 | <td><i>none</i> </td> |
---|
| 5560 | </tr> |
---|
| 5561 | <tr> |
---|
| 5562 | <td><b>clinkflags</b></td> |
---|
| 5563 | <td>The C link flags</td> |
---|
| 5564 | <td><i>none</i> </td> |
---|
| 5565 | </tr> |
---|
| 5566 | </table> |
---|
| 5567 | </p> |
---|
| 5568 | <p> |
---|
| 5569 | <table BORDER='1' COLS='3'> |
---|
| 5570 | <tr> |
---|
| 5571 | <td width="150"><b>cpp</b></td> |
---|
| 5572 | <td width="300">The C++ compiler</td> |
---|
| 5573 | <td width="200"><b>g++</b></td> |
---|
| 5574 | </tr> |
---|
| 5575 | <tr> |
---|
| 5576 | <td><b>cppcomp</b></td> |
---|
| 5577 | <td>The C++ compiling command</td> |
---|
| 5578 | <td><b>$(cpp) -c -I$(inc) $(includes) $(cppflags)</b></td> |
---|
| 5579 | </tr> |
---|
| 5580 | <tr> |
---|
| 5581 | <td><b>cpplink</b></td> |
---|
| 5582 | <td>The C++ linking command</td> |
---|
| 5583 | <td><b>$(cpp) $(cpplinkflags)</b></td> |
---|
| 5584 | </tr> |
---|
| 5585 | <tr> |
---|
| 5586 | <td><b>cppflags</b></td> |
---|
| 5587 | <td>The C++ compilation flags</td> |
---|
| 5588 | <td><i>none</i> </td> |
---|
| 5589 | </tr> |
---|
| 5590 | <tr> |
---|
| 5591 | <td><b>pp_cppflags</b></td> |
---|
| 5592 | <td>The preprocessor flags for C++</td> |
---|
| 5593 | <td><i>none</i> </td> |
---|
| 5594 | </tr> |
---|
| 5595 | <tr> |
---|
| 5596 | <td><b>cpplinkflags</b></td> |
---|
| 5597 | <td>The C++ link flags</td> |
---|
| 5598 | <td><i>none</i> </td> |
---|
| 5599 | </tr> |
---|
| 5600 | </table> |
---|
| 5601 | </p> |
---|
| 5602 | <p> |
---|
| 5603 | <table BORDER='1' COLS='3'> |
---|
| 5604 | <tr> |
---|
| 5605 | <td width="150"><b>for</b></td> |
---|
| 5606 | <td width="300">The Fortran compiler</td> |
---|
| 5607 | <td width="200"><b>f77</b></td> |
---|
| 5608 | </tr> |
---|
| 5609 | <tr> |
---|
| 5610 | <td><b>fcomp</b></td> |
---|
| 5611 | <td>The Fortran compiling command</td> |
---|
| 5612 | <td><b>$(for) -c -I$(inc) $(includes) $(fflags)</b></td> |
---|
| 5613 | </tr> |
---|
| 5614 | <tr> |
---|
| 5615 | <td><b>flink</b></td> |
---|
| 5616 | <td>The Fortran linking command</td> |
---|
| 5617 | <td><b>$(for) $(clinkflags)</b></td> |
---|
| 5618 | </tr> |
---|
| 5619 | <tr> |
---|
| 5620 | <td><b>fflags</b></td> |
---|
| 5621 | <td>The Fortran compilation flags</td> |
---|
| 5622 | <td><i>none</i> </td> |
---|
| 5623 | </tr> |
---|
| 5624 | <tr> |
---|
| 5625 | <td><b>pp_fflags</b></td> |
---|
| 5626 | <td>The preprocessor flags for fortran</td> |
---|
| 5627 | <td><i>none</i> </td> |
---|
| 5628 | </tr> |
---|
| 5629 | <tr> |
---|
| 5630 | <td><b>flinkflags</b></td> |
---|
| 5631 | <td>The Fortran link flags</td> |
---|
| 5632 | <td><i>none</i> </td> |
---|
| 5633 | </tr> |
---|
| 5634 | <tr> |
---|
| 5635 | <td><b>ppcmd</b></td> |
---|
| 5636 | <td>The include file command for Fortran</td> |
---|
| 5637 | <td><b>-I</b></td> |
---|
| 5638 | </tr> |
---|
| 5639 | </table> |
---|
| 5640 | </p> |
---|
| 5641 | <p> |
---|
| 5642 | <table BORDER='1' COLS='3'> |
---|
| 5643 | <tr> |
---|
| 5644 | <td width="150"><b>javacomp</b></td> |
---|
| 5645 | <td width="300">The java compiling command</td> |
---|
| 5646 | <td width="200"><b>javac</b></td> |
---|
| 5647 | </tr> |
---|
| 5648 | <tr> |
---|
| 5649 | <td width="150"><b>jar</b></td> |
---|
| 5650 | <td>The java archiver command</td> |
---|
| 5651 | <td><b>jar</b></td> |
---|
| 5652 | </tr> |
---|
| 5653 | </table> |
---|
| 5654 | </p> |
---|
| 5655 | <p> |
---|
| 5656 | <table BORDER='1' COLS='3'> |
---|
| 5657 | <tr> |
---|
| 5658 | <td width="150"><b>lex</b></td> |
---|
| 5659 | <td width="300">The Lex command</td> |
---|
| 5660 | <td width="200"><b>lex $(lexflags)</b></td> |
---|
| 5661 | </tr> |
---|
| 5662 | <tr> |
---|
| 5663 | <td><b>lexflags</b></td> |
---|
| 5664 | <td>The Lex flags</td> |
---|
| 5665 | <td><i>none</i> </td> |
---|
| 5666 | </tr> |
---|
| 5667 | <tr> |
---|
| 5668 | <td><b>yacc</b></td> |
---|
| 5669 | <td>The Yacc command</td> |
---|
| 5670 | <td><b>yacc $(yaccflags)</b></td> |
---|
| 5671 | </tr> |
---|
| 5672 | <tr> |
---|
| 5673 | <td><b>yaccflags</b></td> |
---|
| 5674 | <td>The Yacc flags</td> |
---|
| 5675 | <td><i>none</i> </td> |
---|
| 5676 | </tr> |
---|
| 5677 | <tr> |
---|
| 5678 | <td><b>ar</b></td> |
---|
| 5679 | <td>The archive command</td> |
---|
| 5680 | <td><b>ar -clr</b></td> |
---|
| 5681 | </tr> |
---|
| 5682 | <tr> |
---|
| 5683 | <td><b>ranlib</b></td> |
---|
| 5684 | <td>The ranlib command</td> |
---|
| 5685 | <td>r<b>anlib</b></td> |
---|
| 5686 | </tr> |
---|
| 5687 | </table> |
---|
| 5688 | </p> |
---|
| 5689 | </cmt:section> |
---|
| 5690 | <cmt:section title="Package customizing macros"> |
---|
| 5691 | |
---|
| 5692 | These macros do not receive default values. They are all |
---|
| 5693 | prefixed by the package name. They are meant to provide |
---|
| 5694 | specific variant to the corresponding generic language related |
---|
| 5695 | macros. |
---|
| 5696 | |
---|
| 5697 | <p>They are automatically and by default concatenated by |
---|
| 5698 | <b>CMT</b> to fill in the corresponding global <i>use</i> |
---|
| 5699 | macros (see appendix on <A HREF="#Generated |
---|
| 5700 | macros">generated macros</A>). However, this concatenation |
---|
| 5701 | mechanism is discarded when the <b>-no_auto_imports</b> |
---|
| 5702 | option is specified in the corresponding use statement.</p> |
---|
| 5703 | |
---|
| 5704 | <p>The <package>_native_version is not subject to |
---|
| 5705 | automatic concatenation.</p> |
---|
| 5706 | |
---|
| 5707 | <p> |
---|
| 5708 | <table BORDER='1' COLS='2'> |
---|
| 5709 | <tr> |
---|
| 5710 | <td WIDTH="250"><b><<i>package</i>>_cflags</b></td> |
---|
| 5711 | <td WIDTH="400">specific C flags</td> |
---|
| 5712 | </tr> |
---|
| 5713 | <tr> |
---|
| 5714 | <td><b><<i>package</i>>_pp_cflags</b></td> |
---|
| 5715 | <td>specific C preprocessor flags</td> |
---|
| 5716 | </tr> |
---|
| 5717 | <tr> |
---|
| 5718 | <td><b><<i>package</i>>_cppflags</b></td> |
---|
| 5719 | <td>specific C++ flags</td> |
---|
| 5720 | </tr> |
---|
| 5721 | <tr> |
---|
| 5722 | <td><b><<i>package</i>>_pp_cppflags</b></td> |
---|
| 5723 | <td>specific C++ preprocessor flags</td> |
---|
| 5724 | </tr> |
---|
| 5725 | <tr> |
---|
| 5726 | <td><b><<i>package</i>>_fflags</b></td> |
---|
| 5727 | <td>specific Fortran flags</td> |
---|
| 5728 | </tr> |
---|
| 5729 | <tr> |
---|
| 5730 | <td><b><<i>package</i>>_pp_fflags</b></td> |
---|
| 5731 | <td>specific Fortran preprocessor flags</td> |
---|
| 5732 | </tr> |
---|
| 5733 | <tr> |
---|
| 5734 | <td><b><<i>package</i>>_libraries</b></td> |
---|
| 5735 | <td> |
---|
| 5736 | gives the (space separated) list of library names exported by this |
---|
| 5737 | package. This list is typically used in the |
---|
| 5738 | <b>cmt build library_links</b> command. |
---|
| 5739 | </td> |
---|
| 5740 | </tr> |
---|
| 5741 | <tr> |
---|
| 5742 | <td><b><<i>package</i>>_linkopts</b></td> |
---|
| 5743 | <td> |
---|
| 5744 | provide the linker options required by any application willing to |
---|
| 5745 | access the different libraries offered by the |
---|
| 5746 | package. This may include support for several libraries |
---|
| 5747 | per package. |
---|
| 5748 | |
---|
| 5749 | <p> |
---|
| 5750 | A typical example of how to define such a macro could be : </p> |
---|
| 5751 | |
---|
| 5752 | <cmt:code> |
---|
| 5753 | macro Cm_linkopts "-L$(CMROOT)/$(Cm_tag) -lCm -lm" |
---|
| 5754 | </cmt:code> |
---|
| 5755 | |
---|
| 5756 | </td> |
---|
| 5757 | </tr> |
---|
| 5758 | <tr> |
---|
| 5759 | <td><b><<i>package</i>>_stamps</b></td> |
---|
| 5760 | <td> |
---|
| 5761 | may contain a list of <i>stamp</i> file names (or make |
---|
| 5762 | targets). Whenever a library is modified, one dedicated |
---|
| 5763 | stamp file is re-created, simply to mark the |
---|
| 5764 | reconstruction date. The name of this stamp file is |
---|
| 5765 | conventionally <b><<i>library</i>>.stamp</b>. |
---|
| 5766 | Thus, a typical definition for this macro could be : |
---|
| 5767 | |
---|
| 5768 | <cmt:code> |
---|
| 5769 | macro Cm_stamps "$(Cm_root)/$(Cm_tag)/Cm.stamp" |
---|
| 5770 | </cmt:code> |
---|
| 5771 | |
---|
| 5772 | <p>Then, these stamp file references are accumulated |
---|
| 5773 | into the standard macro named <b>use_stamps</b> which is |
---|
| 5774 | always installed within the dependency list for |
---|
| 5775 | applications, so that whenever one of the libraries used |
---|
| 5776 | from the hierarchy of used packages changes, the |
---|
| 5777 | application will be automatically rebuilt.</p> |
---|
| 5778 | |
---|
| 5779 | </td> |
---|
| 5780 | </tr> |
---|
| 5781 | |
---|
| 5782 | <tr> |
---|
| 5783 | |
---|
| 5784 | <td><b><<i>package</i>>_native_version</b></td> |
---|
| 5785 | |
---|
| 5786 | <td>specifies the native version of the external |
---|
| 5787 | package referenced by this <i>interface</i> |
---|
| 5788 | package.<br/>When this macro is provided, its value is |
---|
| 5789 | displayed by the <b>cmt show uses</b> command</td> |
---|
| 5790 | |
---|
| 5791 | </tr> |
---|
| 5792 | |
---|
| 5793 | <tr> |
---|
| 5794 | |
---|
| 5795 | <td><b><<i>package</i>>_export_paths</b></td> |
---|
| 5796 | |
---|
| 5797 | <td>specifies the list of files or directories that |
---|
| 5798 | should be exported during the deployment process for |
---|
| 5799 | this package. Generally this is only useful for glue |
---|
| 5800 | packages refering to external software</td> |
---|
| 5801 | |
---|
| 5802 | </tr> |
---|
| 5803 | <tr> |
---|
| 5804 | |
---|
| 5805 | <td><b><<i>package</i>>_home</b></td> |
---|
| 5806 | |
---|
| 5807 | <td>specifies the base location for external software |
---|
| 5808 | described in glue packages. This macro is generally |
---|
| 5809 | used to specify the previous one</td> |
---|
| 5810 | |
---|
| 5811 | </tr> |
---|
| 5812 | </table> |
---|
| 5813 | </p> |
---|
| 5814 | </cmt:section> |
---|
| 5815 | |
---|
| 5816 | <cmt:section title="Constituent specific customizing macros"> |
---|
| 5817 | |
---|
| 5818 | These macros do not receive any default values (ie they are |
---|
| 5819 | empty by default). They are meant to provide for each |
---|
| 5820 | constituent, specific variants to the corresponding generic |
---|
| 5821 | language related macros. |
---|
| 5822 | |
---|
| 5823 | <p>By convention, they are all prefixed by the constituent |
---|
| 5824 | name. But macros used for defining compiler options are in |
---|
| 5825 | addition prefixed by the constituent |
---|
| 5826 | category (either <b>lib_</b>, <b>app_</b> or <b>doc_</b></p> |
---|
| 5827 | |
---|
| 5828 | <p>They are used in the various make fragments for fine |
---|
| 5829 | customization of the build command parameters.</p> |
---|
| 5830 | |
---|
| 5831 | <p> |
---|
| 5832 | <table BORDER='1' COLS='2'> |
---|
| 5833 | <tr> |
---|
| 5834 | <td WIDTH="350"><b><<i>category</i>>_<<i>constituent</i>>_cflags</b></td> |
---|
| 5835 | <td WIDTH="300">specific C flags</td> |
---|
| 5836 | </tr> |
---|
| 5837 | <tr> |
---|
| 5838 | <td><b><<i>category</i>>_<<i>constituent</i>>_pp_cflags</b></td> |
---|
| 5839 | <td>specific C preprocessor flags</td> |
---|
| 5840 | </tr> |
---|
| 5841 | <tr> |
---|
| 5842 | <td><b><<i>category</i>>_<<i>constituent</i>>_cppflags</b></td> |
---|
| 5843 | <td>specific C++ flags</td> |
---|
| 5844 | </tr> |
---|
| 5845 | <tr> |
---|
| 5846 | <td><b><<i>category</i>>_<<i>constituent</i>>_pp_cppflags</b></td> |
---|
| 5847 | <td>specific C++ preprocessor flags</td> |
---|
| 5848 | </tr> |
---|
| 5849 | <tr> |
---|
| 5850 | <td><b><<i>category</i>>_<<i>constituent</i>>_fflags</b></td> |
---|
| 5851 | <td>specific Fortran flags</td> |
---|
| 5852 | </tr> |
---|
| 5853 | <tr> |
---|
| 5854 | <td><b><<i>category</i>>_<<i>constituent</i>>_pp_fflags</b></td> |
---|
| 5855 | <td>specific Fortran preprocessor flags</td> |
---|
| 5856 | </tr> |
---|
| 5857 | <tr> |
---|
| 5858 | <td><b><<i>constituent</i>>linkopts</b></td> |
---|
| 5859 | <td> |
---|
| 5860 | provides additional linker options to the application. It is |
---|
| 5861 | complementary to - and should not be confused with - the |
---|
| 5862 | <b><<i>package</i>>_linkopts</b> macro, which |
---|
| 5863 | provides exported linker options required by clients |
---|
| 5864 | packages to use the package libraries. |
---|
| 5865 | </td> |
---|
| 5866 | </tr> |
---|
| 5867 | <tr> |
---|
| 5868 | <td><b><<i>constituent</i>>_shlibflags</b></td> |
---|
| 5869 | <td> |
---|
| 5870 | provides additional linker options used when building a |
---|
| 5871 | shared library. Generally, a simple shared library does |
---|
| 5872 | not need any external reference to be resolved at build |
---|
| 5873 | time (it is in this case supposed to get its unresolved |
---|
| 5874 | references from other shared libraries). However, |
---|
| 5875 | (typically when one builds a dynamic loading capable |
---|
| 5876 | component) it might be desired to statically link it |
---|
| 5877 | with other libraries (making them somewhat private). |
---|
| 5878 | </td> |
---|
| 5879 | </tr> |
---|
| 5880 | <tr> |
---|
| 5881 | <td><b><<i>constituent</i>>_dependencies</b></td> |
---|
| 5882 | <td> |
---|
| 5883 | provides user defined dependency specifications for each |
---|
| 5884 | constituent. The typical use of this macro is fill it |
---|
| 5885 | with the name of the list of some other constituents |
---|
| 5886 | which <i>have</i> to be rebuilt first (since each |
---|
| 5887 | constituent is associated with a target with the same |
---|
| 5888 | name). This is especially needed when one want to use |
---|
| 5889 | the parallel gmake (ie. the -j option of gmake). |
---|
| 5890 | </td> |
---|
| 5891 | </tr> |
---|
| 5892 | <tr> |
---|
| 5893 | <td><b><<i>group</i>>_dependencies</b></td> |
---|
| 5894 | <td> |
---|
| 5895 | provides user defined dependency specifications for each |
---|
| 5896 | group. The typical use of this macro is fill it |
---|
| 5897 | with the name of the list of some other constituents |
---|
| 5898 | which <i>have</i> to be rebuilt first (since each |
---|
| 5899 | constituent is associated with a target with the same |
---|
| 5900 | name). This is especially needed when one want to use |
---|
| 5901 | the parallel gmake (ie. the -j option of gmake). |
---|
| 5902 | </td> |
---|
| 5903 | </tr> |
---|
| 5904 | </table> |
---|
| 5905 | </p> |
---|
| 5906 | </cmt:section> |
---|
| 5907 | <cmt:section title="Source specific customizing macros"> |
---|
| 5908 | |
---|
| 5909 | These macros do not receive any default values (ie they are |
---|
| 5910 | empty by default). They are meant to provide for each |
---|
| 5911 | source file, specific variants to the corresponding generic |
---|
| 5912 | language related macros. |
---|
| 5913 | |
---|
| 5914 | <p>By convention, they are all prefixed by the source file |
---|
| 5915 | name followed by the source file suffix (either |
---|
| 5916 | <b>_c</b>, <b>_cxx</b>, <b>_f</b>, etc.)</p> |
---|
| 5917 | |
---|
| 5918 | <p>They are used in the various make fragments for fine |
---|
| 5919 | customization of the build command parameters.</p> |
---|
| 5920 | |
---|
| 5921 | <p> |
---|
| 5922 | <table BORDER='1' COLS='2'> |
---|
| 5923 | <tr> |
---|
| 5924 | <td WIDTH="300"><b><<i>constituent</i>>_<<i>suffix</i>>_cflags</b></td> |
---|
| 5925 | <td WIDTH="300">specific C flags</td> |
---|
| 5926 | </tr> |
---|
| 5927 | <tr> |
---|
| 5928 | <td><b><<i>constituent</i>>_<<i>suffix</i>>_cppflags</b></td> |
---|
| 5929 | <td>specific C++ flags</td> |
---|
| 5930 | </tr> |
---|
| 5931 | <tr> |
---|
| 5932 | <td><b><<i>constituent</i>>_<<i>suffix</i>>_fflags</b></td> |
---|
| 5933 | <td>specific Fortran flags</td> |
---|
| 5934 | </tr> |
---|
| 5935 | </table> |
---|
| 5936 | </p> |
---|
| 5937 | </cmt:section> |
---|
| 5938 | <cmt:section title="Generated macros"> |
---|
| 5939 | |
---|
| 5940 | <p> These macros are automatically <i>generated</i> when |
---|
| 5941 | <b>make</b> or most cmt commands are run.</p> |
---|
| 5942 | |
---|
| 5943 | <p>The first set of them provide constant values corresponding |
---|
| 5944 | to <b>CMT</b> based information. They are not meant to be overridden |
---|
| 5945 | by the user, since they serve as a communication mean between |
---|
| 5946 | <b>CMT</b> and the user.</p> |
---|
| 5947 | |
---|
| 5948 | <p> |
---|
| 5949 | <table BORDER='1' COLS='2'> |
---|
| 5950 | <tr> |
---|
| 5951 | <td width="200"><b><<i>PACKAGE</i>>ROOT</b></td> |
---|
| 5952 | <td width="400">The access path of the package (including the version branch)</td> |
---|
| 5953 | </tr> |
---|
| 5954 | <tr> |
---|
| 5955 | <td><b><<i>package</i>>_root</b></td> |
---|
| 5956 | <td>The access path of the package (including the version branch). This macro is very similar to the <b><<i>PACKAGE</i>>ROOT</b> macro except that it tries to use a relative path instead of an absolute one. </td> |
---|
| 5957 | </tr> |
---|
| 5958 | <tr> |
---|
| 5959 | <td><b><<i>PACKAGE</i>>VERSION</b></td> |
---|
| 5960 | <td>The used version of the package</td> |
---|
| 5961 | </tr> |
---|
| 5962 | <tr> |
---|
| 5963 | <td><b>PACKAGE_ROOT</b></td> |
---|
| 5964 | <td>The access path of the current package (including the version branch)</td> |
---|
| 5965 | </tr> |
---|
| 5966 | <tr> |
---|
| 5967 | <td><b>package</b></td> |
---|
| 5968 | <td>The name of the current package</td> |
---|
| 5969 | </tr> |
---|
| 5970 | <tr> |
---|
| 5971 | <td><b>version</b></td> |
---|
| 5972 | <td>The version tag of the current package</td> |
---|
| 5973 | </tr> |
---|
| 5974 | <tr> |
---|
| 5975 | <td><b>package_offset</b></td> |
---|
| 5976 | <td>The directory offset of the current package</td> |
---|
| 5977 | </tr> |
---|
| 5978 | <tr> |
---|
| 5979 | <td><b>package_cmtpath</b></td> |
---|
| 5980 | <td>The package area where the current package has been found</td> |
---|
| 5981 | </tr> |
---|
| 5982 | <tr> |
---|
| 5983 | <td><b><<i>package</i>>_cmtpath</b></td> |
---|
| 5984 | <td>The package area where the corresponding package has been found</td> |
---|
| 5985 | </tr> |
---|
| 5986 | <tr> |
---|
| 5987 | <td><b><<i>package</i>>_offset</b></td> |
---|
| 5988 | <td>The directory offset of the corresponding package</td> |
---|
| 5989 | </tr> |
---|
| 5990 | </table> |
---|
| 5991 | </p> |
---|
| 5992 | |
---|
| 5993 | <p>The second set is deduced from the context and from the |
---|
| 5994 | requirements file of the package. They can be overridden by |
---|
| 5995 | the user so as to customize the <b>CMT</b> behaviour.</p> |
---|
| 5996 | |
---|
| 5997 | <p> |
---|
| 5998 | <table BORDER='1' COLS='2'> |
---|
| 5999 | <tr> |
---|
| 6000 | <td width="220"><b><<i>package</i>>_tag</b></td> |
---|
| 6001 | <td width="400">The specific configuration tag for the package. By default it is set to $(tag) but can be freely overridden</td> |
---|
| 6002 | </tr> |
---|
| 6003 | <tr> |
---|
| 6004 | <td><b>constituents</b></td> |
---|
| 6005 | <td>The ordered set of constituents declared without any group option</td> |
---|
| 6006 | </tr> |
---|
| 6007 | <tr> |
---|
| 6008 | <td><b><i><group-name></i>_constituents</b></td> |
---|
| 6009 | <td>The ordered set of all constituents declared using a group=<group-name> option</td> |
---|
| 6010 | </tr> |
---|
| 6011 | </table> |
---|
| 6012 | </p> |
---|
| 6013 | |
---|
| 6014 | <p>The third set of generated macros are the <i>global use |
---|
| 6015 | macros</i>. They correspond to the concatenation of the |
---|
| 6016 | corresponding package specific customizing options that can be |
---|
| 6017 | deduced from the ordered set of <i>use</i> statements found in |
---|
| 6018 | the requirements file (taking into account the complete |
---|
| 6019 | hierarchy of used packages with the exception of those |
---|
| 6020 | specified with the <br/><b>-no_auto_imports</b> option in their use |
---|
| 6021 | statement) :</p> |
---|
| 6022 | |
---|
| 6023 | <p> |
---|
| 6024 | <table BORDER='1' COLS='2'> |
---|
| 6025 | <tr> |
---|
| 6026 | <td width="150"><b>use_cflags</b></td> |
---|
| 6027 | <td width="400">C compiler flags</td> |
---|
| 6028 | </tr> |
---|
| 6029 | <tr> |
---|
| 6030 | <td><b>use_pp_cflags</b></td> |
---|
| 6031 | <td>Preprocessor flags for the C language</td> |
---|
| 6032 | </tr> |
---|
| 6033 | <tr> |
---|
| 6034 | <td><b>use_cppflags</b></td> |
---|
| 6035 | <td>C++ compiler flags</td> |
---|
| 6036 | </tr> |
---|
| 6037 | <tr> |
---|
| 6038 | <td><b>use_pp_cppflags</b></td> |
---|
| 6039 | <td>Preprocessor flags for the C++ language</td> |
---|
| 6040 | </tr> |
---|
| 6041 | <tr> |
---|
| 6042 | <td><b>use_fflags</b></td> |
---|
| 6043 | <td>Fortran compiler flags</td> |
---|
| 6044 | </tr> |
---|
| 6045 | <tr> |
---|
| 6046 | <td><b>use_pp_fflags</b></td> |
---|
| 6047 | <td>Preprocessor flags for the Fortran language</td> |
---|
| 6048 | </tr> |
---|
| 6049 | <tr> |
---|
| 6050 | <td><b>use_libraries</b></td> |
---|
| 6051 | <td>List of library names</td> |
---|
| 6052 | </tr> |
---|
| 6053 | <tr> |
---|
| 6054 | <td><b>use_linkopts</b></td> |
---|
| 6055 | <td>Linker options</td> |
---|
| 6056 | </tr> |
---|
| 6057 | <tr> |
---|
| 6058 | <td><b>use_stamps</b></td> |
---|
| 6059 | <td>Dependency stamps</td> |
---|
| 6060 | </tr> |
---|
| 6061 | <tr> |
---|
| 6062 | <td><b>use_requirements</b></td> |
---|
| 6063 | <td>The set of used requirements</td> |
---|
| 6064 | </tr> |
---|
| 6065 | <tr> |
---|
| 6066 | <td><b>use_includes</b></td> |
---|
| 6067 | <td>The set of include search paths options for the preprocessor from the used packages</td> |
---|
| 6068 | </tr> |
---|
| 6069 | <tr> |
---|
| 6070 | <td><b>use_fincludes</b></td> |
---|
| 6071 | <td>The set of include search paths options for the fortran preprocessor from the used packages</td> |
---|
| 6072 | </tr> |
---|
| 6073 | <tr> |
---|
| 6074 | <td><b>includes</b></td> |
---|
| 6075 | <td>The overall set of include search paths for the preprocessor</td> |
---|
| 6076 | </tr> |
---|
| 6077 | <tr> |
---|
| 6078 | <td><b>fincludes</b></td> |
---|
| 6079 | <td>The overall set of include search paths options for the fortran preprocessor</td> |
---|
| 6080 | </tr> |
---|
| 6081 | </table> |
---|
| 6082 | </p> |
---|
| 6083 | |
---|
| 6084 | </cmt:section> |
---|
| 6085 | |
---|
| 6086 | <cmt:section title="Utility macros"> |
---|
| 6087 | |
---|
| 6088 | These macros are used to specify the behaviour of various |
---|
| 6089 | actions in CMT. |
---|
| 6090 | |
---|
| 6091 | <p> |
---|
| 6092 | <table BORDER='1' COLS='2'> |
---|
| 6093 | <tr> |
---|
| 6094 | <td width="150"><b>X11_cflags</b></td> |
---|
| 6095 | <td width="400">compilation flags for X11</td> |
---|
| 6096 | </tr> |
---|
| 6097 | <tr> |
---|
| 6098 | <td><b>Xm_cflags</b></td> |
---|
| 6099 | <td>compilation flags for Motif</td> |
---|
| 6100 | </tr> |
---|
| 6101 | <tr> |
---|
| 6102 | <td><b>X_linkopts</b></td> |
---|
| 6103 | <td>Link options for XWindows (and Motif)</td> |
---|
| 6104 | </tr> |
---|
| 6105 | <tr> |
---|
| 6106 | <td><b>make_shlib</b></td> |
---|
| 6107 | <td>The command used to generate the shared library from the static one</td> |
---|
| 6108 | </tr> |
---|
| 6109 | <tr> |
---|
| 6110 | <td><b>shlibsuffix</b></td> |
---|
| 6111 | <td>The system dependent suffix for shared libraries</td> |
---|
| 6112 | </tr> |
---|
| 6113 | <tr> |
---|
| 6114 | <td><b>shlibbuilder</b></td> |
---|
| 6115 | <td>The loader used to build the shared library</td> |
---|
| 6116 | </tr> |
---|
| 6117 | <tr> |
---|
| 6118 | <td><b>shlibflags</b></td> |
---|
| 6119 | <td>The additional options given to the shared library builder</td> |
---|
| 6120 | </tr> |
---|
| 6121 | <tr> |
---|
| 6122 | <td><b>symlink</b></td> |
---|
| 6123 | <td>The command used to install a symbolic link</td> |
---|
| 6124 | </tr> |
---|
| 6125 | <tr> |
---|
| 6126 | <td><b></b></td> |
---|
| 6127 | <td>The command used to remove a symbolic link</td> |
---|
| 6128 | </tr> |
---|
| 6129 | <tr> |
---|
| 6130 | <td><b>build_prototype</b></td> |
---|
| 6131 | <td>The command used to generate the C prototype header file (default to the internal cmt dedicated command)</td> |
---|
| 6132 | </tr> |
---|
| 6133 | <tr> |
---|
| 6134 | <td><b>build_dependencies</b></td> |
---|
| 6135 | <td>The command used to generate dependencies (default to the internal cmt dedicated command)</td> |
---|
| 6136 | </tr> |
---|
| 6137 | <tr> |
---|
| 6138 | <td><b>lock_command</b></td> |
---|
| 6139 | <td>The command used to physically lock a package</td> |
---|
| 6140 | </tr> |
---|
| 6141 | <tr> |
---|
| 6142 | <td><b>unlock_command</b></td> |
---|
| 6143 | <td>The command used to physically unlock a package</td> |
---|
| 6144 | </tr> |
---|
| 6145 | <tr> |
---|
| 6146 | <td><b>make_hosts</b></td> |
---|
| 6147 | <td>The list of remote host names which exactly require the <b>make</b> command</td> |
---|
| 6148 | </tr> |
---|
| 6149 | <tr> |
---|
| 6150 | <td><b>gmake_hosts</b></td> |
---|
| 6151 | <td>The list of remote host names which exactly require the <b>gmake</b> command</td> |
---|
| 6152 | </tr> |
---|
| 6153 | </table> |
---|
| 6154 | </p> |
---|
| 6155 | |
---|
| 6156 | </cmt:section> |
---|
| 6157 | </cmt:section> |
---|
| 6158 | |
---|
| 6159 | <cmt:section title="Standard templates for makefile fragments"> |
---|
| 6160 | |
---|
| 6161 | <p> |
---|
| 6162 | <table BORDER='1' COLS='3'> |
---|
| 6163 | <tr> |
---|
| 6164 | <td width="150"><center><i>template name</i></center></td> |
---|
| 6165 | <td width="200"><center><i>usage</i></center></td> |
---|
| 6166 | <td width="400"><center><i>used in fragment</i></center></td> |
---|
| 6167 | </tr> |
---|
| 6168 | <tr> |
---|
| 6169 | <td>ADDINCLUDE</td> |
---|
| 6170 | <td>additional include path</td> |
---|
| 6171 | <td><<i>language</i>> java</td> |
---|
| 6172 | </tr> |
---|
| 6173 | <tr> |
---|
| 6174 | <td>CONSTITUENT</td> |
---|
| 6175 | <td>name of the constituent</td> |
---|
| 6176 | <td><<i>language</i>> java jar make_header jar_header java_header library_header application_header protos_header library_no_share library application dependencies cleanup_header cleanup_library cleanup_application check_application document_header <document> trailer dsw_all_project_dependency dsw_project dsp_library_header dsp_shared_library_header dsp_windows_header dsp_application_header dsp_trailer constituent check_application_header</td> |
---|
| 6177 | </tr> |
---|
| 6178 | <tr> |
---|
| 6179 | <td>DATE</td> |
---|
| 6180 | <td>now</td> |
---|
| 6181 | <td>make_header</td> |
---|
| 6182 | </tr> |
---|
| 6183 | <tr> |
---|
| 6184 | <td>FILENAME</td> |
---|
| 6185 | <td>file name without path</td> |
---|
| 6186 | <td>buildproto <<i>language</i>> <<i>document</i>></td> |
---|
| 6187 | </tr> |
---|
| 6188 | <tr> |
---|
| 6189 | <td>FILEPATH</td> |
---|
| 6190 | <td>file path</td> |
---|
| 6191 | <td>buildproto <<i>language</i>> <<i>document</i>></td> |
---|
| 6192 | </tr> |
---|
| 6193 | <tr> |
---|
| 6194 | <td>FILESUFFIX</td> |
---|
| 6195 | <td>file suffix (without dot)</td> |
---|
| 6196 | <td><<i>language</i>></td> |
---|
| 6197 | </tr> |
---|
| 6198 | <tr> |
---|
| 6199 | <td>FILESUFFIX</td> |
---|
| 6200 | <td>file suffix (with dot)</td> |
---|
| 6201 | <td><<i>document</i>></td> |
---|
| 6202 | </tr> |
---|
| 6203 | <tr> |
---|
| 6204 | <td>FULLNAME</td> |
---|
| 6205 | <td>complete file path and name</td> |
---|
| 6206 | <td><<i>language</i>> cleanup <<i>document</i>> dsp_contents</td> |
---|
| 6207 | </tr> |
---|
| 6208 | <tr> |
---|
| 6209 | <td>GROUP</td> |
---|
| 6210 | <td>group name</td> |
---|
| 6211 | <td>constituents_header</td> |
---|
| 6212 | </tr> |
---|
| 6213 | <tr> |
---|
| 6214 | <td>LINE</td> |
---|
| 6215 | <td>source files</td> |
---|
| 6216 | <td><<i>language</i>> dependencies constituent</td> |
---|
| 6217 | </tr> |
---|
| 6218 | <tr> |
---|
| 6219 | <td>LINKMACRO</td> |
---|
| 6220 | <td>link macro</td> |
---|
| 6221 | <td>application</td> |
---|
| 6222 | </tr> |
---|
| 6223 | <tr> |
---|
| 6224 | <td>NAME</td> |
---|
| 6225 | <td>file name without path and suffix</td> |
---|
| 6226 | <td>buildproto <<i>language</i>> java <<i>document</i>></td> |
---|
| 6227 | </tr> |
---|
| 6228 | <tr> |
---|
| 6229 | <td>OBJS</td> |
---|
| 6230 | <td>object files</td> |
---|
| 6231 | <td>jar_header java_header jar library_no_share library application cleanup_java document_header trailer</td> |
---|
| 6232 | </tr> |
---|
| 6233 | <tr> |
---|
| 6234 | <td>OUTPUTNAME</td> |
---|
| 6235 | <td>output file name</td> |
---|
| 6236 | <td>java</td> |
---|
| 6237 | </tr> |
---|
| 6238 | <tr> |
---|
| 6239 | <td>PACKAGE</td> |
---|
| 6240 | <td>current package name</td> |
---|
| 6241 | <td><<i>language</i>> dsw_header dsw_all_project dsw_all_project_trailer dsw_trailer dsp_all readme_header readme readme_use readme_trailer</td> |
---|
| 6242 | </tr> |
---|
| 6243 | <tr> |
---|
| 6244 | <td>PACKAGEPATH</td> |
---|
| 6245 | <td>current package location</td> |
---|
| 6246 | <td>readme_use</td> |
---|
| 6247 | </tr> |
---|
| 6248 | <tr> |
---|
| 6249 | <td>PROTOSTAMPS</td> |
---|
| 6250 | <td>prototype stamp files</td> |
---|
| 6251 | <td>protos_header</td> |
---|
| 6252 | </tr> |
---|
| 6253 | <tr> |
---|
| 6254 | <td>PROTOTARGET</td> |
---|
| 6255 | <td>prototype target name</td> |
---|
| 6256 | <td>library_header application_header</td> |
---|
| 6257 | </tr> |
---|
| 6258 | <tr> |
---|
| 6259 | <td>SUFFIX</td> |
---|
| 6260 | <td>document suffix</td> |
---|
| 6261 | <td><<i>document</i>></td> |
---|
| 6262 | </tr> |
---|
| 6263 | <tr> |
---|
| 6264 | <td>TITLE</td> |
---|
| 6265 | <td>title for make header</td> |
---|
| 6266 | <td>make_header</td> |
---|
| 6267 | </tr> |
---|
| 6268 | <tr> |
---|
| 6269 | <td>USER</td> |
---|
| 6270 | <td>user name</td> |
---|
| 6271 | <td>make_header</td> |
---|
| 6272 | </tr> |
---|
| 6273 | <tr> |
---|
| 6274 | <td>VERSION</td> |
---|
| 6275 | <td>current package version tag</td> |
---|
| 6276 | <td>readme_header readme readme_use</td> |
---|
| 6277 | </tr> |
---|
| 6278 | </table> |
---|
| 6279 | </p> |
---|
| 6280 | |
---|
| 6281 | </cmt:section> |
---|
| 6282 | |
---|
| 6283 | <cmt:section title="Makefile generation sequences"> |
---|
| 6284 | |
---|
| 6285 | <cmt:blockquote> |
---|
| 6286 | |
---|
| 6287 | This section describes the various makefile generation sequences |
---|
| 6288 | provided by <b>CMT</b>. Each sequence description shows the |
---|
| 6289 | precise set of <a href="#make_fragment">make fragments</a> used |
---|
| 6290 | during the operation. |
---|
| 6291 | |
---|
| 6292 | </cmt:blockquote> |
---|
| 6293 | |
---|
| 6294 | <p> |
---|
| 6295 | <table border='1' cols='3'> |
---|
| 6296 | |
---|
| 6297 | <tr> |
---|
| 6298 | <td width="200"><center><i>Generated makefile</i></center></td> |
---|
| 6299 | <td width="250"><center><i>description</i></center></td> |
---|
| 6300 | <td width="350"><center><i>used make fragments</i></center></td> |
---|
| 6301 | </tr> |
---|
| 6302 | |
---|
| 6303 | <tr> |
---|
| 6304 | <td><b>constituents.make</b></td> |
---|
| 6305 | <td>the main entry point point for all constituent targets</td> |
---|
| 6306 | <td> |
---|
| 6307 | <ol> |
---|
| 6308 | <li>constituents_header</li> |
---|
| 6309 | <li>constituent</li> |
---|
| 6310 | <li>check_application_header</li> |
---|
| 6311 | </ol> |
---|
| 6312 | </td> |
---|
| 6313 | </tr> |
---|
| 6314 | |
---|
| 6315 | <tr> |
---|
| 6316 | <td><b><<i>constituent</i>>.make</b></td> |
---|
| 6317 | <td>application or library specific make fragment</td> |
---|
| 6318 | <td> |
---|
| 6319 | <ol> |
---|
| 6320 | <li>make_header</li> |
---|
| 6321 | <li>java_header | jar_header | library_header | application_header</li> |
---|
| 6322 | <li>protos_header</li> |
---|
| 6323 | <li>buildproto</li> |
---|
| 6324 | <li>jar | library | library_no_share | application</li> |
---|
| 6325 | <li>dependencies</li> |
---|
| 6326 | <li><language> | <language>_library | java</li> |
---|
| 6327 | <li>cleanup_header</li> |
---|
| 6328 | <li>cleanup</li> |
---|
| 6329 | <li>cleanup_application</li> |
---|
| 6330 | <li>cleanup_objects</li> |
---|
| 6331 | <li>cleanup_java</li> |
---|
| 6332 | <li>cleanup_library</li> |
---|
| 6333 | <li>check_application</li> |
---|
| 6334 | </ol> |
---|
| 6335 | </td> |
---|
| 6336 | </tr> |
---|
| 6337 | |
---|
| 6338 | <tr> |
---|
| 6339 | <td><b><<i>constituent</i>>.make</b></td> |
---|
| 6340 | <td>document specific make fragment</td> |
---|
| 6341 | <td> |
---|
| 6342 | <ol> |
---|
| 6343 | <li>make_header</li> |
---|
| 6344 | <li>document_header</li> |
---|
| 6345 | <li>dependencies</li> |
---|
| 6346 | <li><document></li> |
---|
| 6347 | <li><document-trailer></li> |
---|
| 6348 | <li>cleanup_header</li> |
---|
| 6349 | </ol> |
---|
| 6350 | </td> |
---|
| 6351 | </tr> |
---|
| 6352 | |
---|
| 6353 | |
---|
| 6354 | <tr> |
---|
| 6355 | <td><b><package>.dsw</b></td> |
---|
| 6356 | <td>Visual workspace configuration files</td> |
---|
| 6357 | <td> |
---|
| 6358 | <ol> |
---|
| 6359 | <li>dsw_header</li> |
---|
| 6360 | <li>dsw_all_project_header</li> |
---|
| 6361 | <li>dsw_all_project_dependency</li> |
---|
| 6362 | <li>dsw_all_project_trailer</li> |
---|
| 6363 | <li>dsw_project</li> |
---|
| 6364 | <li>dsw_trailer</li> |
---|
| 6365 | <li>dsp_all</li> |
---|
| 6366 | </ol> |
---|
| 6367 | </td> |
---|
| 6368 | </tr> |
---|
| 6369 | |
---|
| 6370 | |
---|
| 6371 | <tr> |
---|
| 6372 | <td><b><constituent>.dsp</b></td> |
---|
| 6373 | <td>Visual project configuration files</td> |
---|
| 6374 | <td> |
---|
| 6375 | <ol> |
---|
| 6376 | <li>dsp_library_header | dsp_shared_library_header | dsp_windows_header | dsp_application_header</li> |
---|
| 6377 | <li>dsp_contents</li> |
---|
| 6378 | <li>dsp_trailer</li> |
---|
| 6379 | </ol> |
---|
| 6380 | </td> |
---|
| 6381 | </tr> |
---|
| 6382 | |
---|
| 6383 | |
---|
| 6384 | <tr> |
---|
| 6385 | <td><b>README</b></td> |
---|
| 6386 | <td>.</td> |
---|
| 6387 | <td> |
---|
| 6388 | <ol> |
---|
| 6389 | <li>readme_header</li> |
---|
| 6390 | <li>readme</li> |
---|
| 6391 | <li>readme_use</li> |
---|
| 6392 | <li>readme_trailer</li> |
---|
| 6393 | </ol> |
---|
| 6394 | </td> |
---|
| 6395 | </tr> |
---|
| 6396 | |
---|
| 6397 | |
---|
| 6398 | </table> |
---|
| 6399 | </p> |
---|
| 6400 | </cmt:section> |
---|
| 6401 | |
---|
| 6402 | <cmt:section title="The complete requirements syntax"> |
---|
| 6403 | |
---|
| 6404 | The syntax of specification statements that can be installed |
---|
| 6405 | in a <b>requirements</b> file are : |
---|
| 6406 | |
---|
| 6407 | <cmt:syntax rule-width="220" name="CMT"> |
---|
| 6408 | <cmt:rule name="cmt-statement"> |
---|
| 6409 | <cmt:alt><cmt:ruleref name="application"/></cmt:alt> |
---|
| 6410 | <cmt:alt><cmt:ruleref name="apply_pattern"/></cmt:alt> |
---|
| 6411 | <cmt:alt><cmt:ruleref name="apply_tag"/></cmt:alt> |
---|
| 6412 | <cmt:alt><cmt:ruleref name="author"/></cmt:alt> |
---|
| 6413 | <cmt:alt><cmt:ruleref name="branches"/></cmt:alt> |
---|
| 6414 | <cmt:alt><cmt:ruleref name="build_strategy"/></cmt:alt> |
---|
| 6415 | <cmt:alt><cmt:ruleref name="cleanup_script"/></cmt:alt> |
---|
| 6416 | <cmt:alt><cmt:ruleref name="cmtpath_pattern"/></cmt:alt> |
---|
| 6417 | <cmt:alt><cmt:ruleref name="document"/></cmt:alt> |
---|
| 6418 | <cmt:alt><cmt:ruleref name="ignore_pattern"/></cmt:alt> |
---|
| 6419 | <cmt:alt><cmt:ruleref name="include_dirs"/></cmt:alt> |
---|
| 6420 | <cmt:alt><cmt:ruleref name="include_path"/></cmt:alt> |
---|
| 6421 | <cmt:alt><cmt:ruleref name="language"/></cmt:alt> |
---|
| 6422 | <cmt:alt><cmt:ruleref name="library"/></cmt:alt> |
---|
| 6423 | <cmt:alt><cmt:ruleref name="make_fragment"/></cmt:alt> |
---|
| 6424 | <cmt:alt><cmt:ruleref name="manager"/></cmt:alt> |
---|
| 6425 | <cmt:alt><cmt:ruleref name="package"/></cmt:alt> |
---|
| 6426 | <cmt:alt><cmt:ruleref name="pattern"/></cmt:alt> |
---|
| 6427 | <cmt:alt><cmt:ruleref name="private"/></cmt:alt> |
---|
| 6428 | <cmt:alt><cmt:ruleref name="public"/></cmt:alt> |
---|
| 6429 | <cmt:alt><cmt:ruleref name="setup_script"/></cmt:alt> |
---|
| 6430 | <cmt:alt><cmt:ruleref name="setup_strategy"/></cmt:alt> |
---|
| 6431 | <cmt:alt><cmt:ruleref name="symbol"/></cmt:alt> |
---|
| 6432 | <cmt:alt><cmt:ruleref name="tag"/></cmt:alt> |
---|
| 6433 | <cmt:alt><cmt:ruleref name="tag_exclude"/></cmt:alt> |
---|
| 6434 | <cmt:alt><cmt:ruleref name="use"/></cmt:alt> |
---|
| 6435 | <cmt:alt><cmt:ruleref name="version"/></cmt:alt> |
---|
| 6436 | <cmt:alt></cmt:alt> |
---|
| 6437 | </cmt:rule> |
---|
| 6438 | <cmt:rule name="alias"> |
---|
| 6439 | <cmt:alt> |
---|
| 6440 | <cmt:kwd/> |
---|
| 6441 | <cmt:term name="alias-name"/> |
---|
| 6442 | <cmt:term name="default-value"/> |
---|
| 6443 | <cmt:optionseq> |
---|
| 6444 | <cmt:ruleref name="tag-expr"/> |
---|
| 6445 | <cmt:term name="value"/> |
---|
| 6446 | </cmt:optionseq> |
---|
| 6447 | </cmt:alt> |
---|
| 6448 | </cmt:rule> |
---|
| 6449 | <cmt:rule name="application"> |
---|
| 6450 | <cmt:alt> |
---|
| 6451 | <cmt:kwd/> |
---|
| 6452 | <cmt:term name="application-name"/> |
---|
| 6453 | <cmt:optionseq> |
---|
| 6454 | <cmt:ruleref name="constituent-option"/> |
---|
| 6455 | </cmt:optionseq> |
---|
| 6456 | </cmt:alt> |
---|
| 6457 | <cmt:continuation> |
---|
| 6458 | <cmt:optionseq> |
---|
| 6459 | <cmt:ruleref name="source"/> |
---|
| 6460 | </cmt:optionseq> |
---|
| 6461 | </cmt:continuation> |
---|
| 6462 | </cmt:rule> |
---|
| 6463 | <cmt:rule name="constituent-option"> |
---|
| 6464 | <cmt:alt><cmt:kwd name="-OS9"/></cmt:alt> |
---|
| 6465 | <cmt:alt><cmt:kwd name="-windows"/></cmt:alt> |
---|
| 6466 | <cmt:alt><cmt:kwd name="-no_share"/></cmt:alt> |
---|
| 6467 | <cmt:alt><cmt:kwd name="-no_static"/></cmt:alt> |
---|
| 6468 | <cmt:alt><cmt:kwd name="-prototypes"/></cmt:alt> |
---|
| 6469 | <cmt:alt><cmt:kwd name="-no_prototypes"/></cmt:alt> |
---|
| 6470 | <cmt:alt><cmt:kwd name="-check"/></cmt:alt> |
---|
| 6471 | <cmt:alt><cmt:kwd name="-group" value="group-name"/></cmt:alt> |
---|
| 6472 | <cmt:alt><cmt:kwd name="-suffix" value="output-suffix"/></cmt:alt> |
---|
| 6473 | <cmt:alt><cmt:kwd name="-import" value="package-name"/></cmt:alt> |
---|
| 6474 | <cmt:alt> |
---|
| 6475 | <cmt:term name="variable-name"/> |
---|
| 6476 | <cmt:kwd name="="/> |
---|
| 6477 | <cmt:term name="variable-value"/> |
---|
| 6478 | </cmt:alt> |
---|
| 6479 | </cmt:rule> |
---|
| 6480 | <cmt:rule name="source"> |
---|
| 6481 | <cmt:alt> |
---|
| 6482 | <cmt:option> |
---|
| 6483 | <cmt:kwd name="-s" value="new-search-path"/> |
---|
| 6484 | </cmt:option> |
---|
| 6485 | <cmt:term name="file-name"/> |
---|
| 6486 | </cmt:alt> |
---|
| 6487 | </cmt:rule> |
---|
| 6488 | <cmt:rule name="apply_pattern"> |
---|
| 6489 | <cmt:alt> |
---|
| 6490 | <cmt:kwd/> |
---|
| 6491 | <cmt:term name="pattern-name"/> |
---|
| 6492 | <cmt:optionseq> |
---|
| 6493 | <cmt:term name="template-name"/> |
---|
| 6494 | <cmt:kwd name="="/> |
---|
| 6495 | <cmt:term name="value"/> |
---|
| 6496 | </cmt:optionseq> |
---|
| 6497 | </cmt:alt> |
---|
| 6498 | </cmt:rule> |
---|
| 6499 | <cmt:rule name="apply_tag"> |
---|
| 6500 | <cmt:alt> |
---|
| 6501 | <cmt:kwd/> |
---|
| 6502 | <cmt:term name="tag-name"/> |
---|
| 6503 | <cmt:optionseq> |
---|
| 6504 | <cmt:term name="tag-name"/> |
---|
| 6505 | </cmt:optionseq> |
---|
| 6506 | </cmt:alt> |
---|
| 6507 | </cmt:rule> |
---|
| 6508 | <cmt:rule name="author"> |
---|
| 6509 | <cmt:alt> |
---|
| 6510 | <cmt:kwd/> |
---|
| 6511 | <cmt:term name="author-name"/> |
---|
| 6512 | </cmt:alt> |
---|
| 6513 | </cmt:rule> |
---|
| 6514 | <cmt:rule name="branches"> |
---|
| 6515 | <cmt:alt> |
---|
| 6516 | <cmt:kwd/> |
---|
| 6517 | <cmt:seq><cmt:term name="branch-name"/></cmt:seq> |
---|
| 6518 | </cmt:alt> |
---|
| 6519 | </cmt:rule> |
---|
| 6520 | <cmt:rule name="build_strategy"> |
---|
| 6521 | <cmt:alt> |
---|
| 6522 | <cmt:kwd/> |
---|
| 6523 | <cmt:term name="build-strategy-name"/> |
---|
| 6524 | </cmt:alt> |
---|
| 6525 | </cmt:rule> |
---|
| 6526 | <cmt:rule name="build-strategy-name"> |
---|
| 6527 | <cmt:alt><cmt:kwd name="prototypes"/></cmt:alt> |
---|
| 6528 | <cmt:alt><cmt:kwd name="no_prototypes"/></cmt:alt> |
---|
| 6529 | <cmt:alt><cmt:kwd name="keep_makefiles"/></cmt:alt> |
---|
| 6530 | <cmt:alt><cmt:kwd name="rebuild_makefiles"/></cmt:alt> |
---|
| 6531 | <cmt:alt><cmt:kwd name="with_install_area"/></cmt:alt> |
---|
| 6532 | <cmt:alt><cmt:kwd name="without_install_area"/></cmt:alt> |
---|
| 6533 | </cmt:rule> |
---|
| 6534 | <cmt:rule name="cleanup_script"> |
---|
| 6535 | <cmt:alt> |
---|
| 6536 | <cmt:kwd/> |
---|
| 6537 | <cmt:term name="script-name"/> |
---|
| 6538 | </cmt:alt> |
---|
| 6539 | </cmt:rule> |
---|
| 6540 | <cmt:rule name="cmtpath_pattern"> |
---|
| 6541 | <cmt:alt> |
---|
| 6542 | <cmt:kwd/> |
---|
| 6543 | <cmt:ruleref name="cmt-statement"/> |
---|
| 6544 | </cmt:alt> |
---|
| 6545 | <cmt:continuation> |
---|
| 6546 | <cmt:optionseq> |
---|
| 6547 | <cmt:kwd name=" ; "/> |
---|
| 6548 | <cmt:ruleref name="cmt-statement"/> |
---|
| 6549 | </cmt:optionseq> |
---|
| 6550 | </cmt:continuation> |
---|
| 6551 | </cmt:rule> |
---|
| 6552 | <cmt:rule name="document"> |
---|
| 6553 | <cmt:alt> |
---|
| 6554 | <cmt:kwd/> |
---|
| 6555 | <cmt:term name="document-name"/> |
---|
| 6556 | <cmt:optionseq> |
---|
| 6557 | <cmt:ruleref name="constituent-option"/> |
---|
| 6558 | </cmt:optionseq> |
---|
| 6559 | </cmt:alt> |
---|
| 6560 | <cmt:continuation> |
---|
| 6561 | <cmt:optionseq> |
---|
| 6562 | <cmt:ruleref name="source"/> |
---|
| 6563 | </cmt:optionseq> |
---|
| 6564 | </cmt:continuation> |
---|
| 6565 | </cmt:rule> |
---|
| 6566 | <cmt:rule name="ignore_pattern"> |
---|
| 6567 | <cmt:alt> |
---|
| 6568 | <cmt:kwd/> |
---|
| 6569 | <cmt:term name="pattern-name"/> |
---|
| 6570 | </cmt:alt> |
---|
| 6571 | </cmt:rule> |
---|
| 6572 | <cmt:rule name="include_dirs"> |
---|
| 6573 | <cmt:alt> |
---|
| 6574 | <cmt:kwd/> |
---|
| 6575 | <cmt:term name="search-path"/> |
---|
| 6576 | </cmt:alt> |
---|
| 6577 | </cmt:rule> |
---|
| 6578 | <cmt:rule name="include_path"> |
---|
| 6579 | <cmt:alt> |
---|
| 6580 | <cmt:kwd/> |
---|
| 6581 | <cmt:term name="search-path"/> |
---|
| 6582 | </cmt:alt> |
---|
| 6583 | </cmt:rule> |
---|
| 6584 | <cmt:rule name="language"> |
---|
| 6585 | <cmt:alt> |
---|
| 6586 | <cmt:kwd/> |
---|
| 6587 | <cmt:term name="language-name"/> |
---|
| 6588 | <cmt:optionseq> |
---|
| 6589 | <cmt:ruleref name="language-option"/> |
---|
| 6590 | </cmt:optionseq> |
---|
| 6591 | </cmt:alt> |
---|
| 6592 | </cmt:rule> |
---|
| 6593 | <cmt:rule name="language-option"> |
---|
| 6594 | <cmt:alt><cmt:kwd name="-suffix" value="suffix"/></cmt:alt> |
---|
| 6595 | <cmt:alt><cmt:kwd name="-linker" value="linker-command"/></cmt:alt> |
---|
| 6596 | <cmt:alt><cmt:kwd name="-prototypes"/></cmt:alt> |
---|
| 6597 | <cmt:alt><cmt:kwd name="-preprocessor_command" value="preprocessor_command"/></cmt:alt> |
---|
| 6598 | <cmt:alt><cmt:kwd name="-fragment" value="fragment"/></cmt:alt> |
---|
| 6599 | <cmt:alt><cmt:kwd name="-output_suffix" value="output-suffix"/></cmt:alt> |
---|
| 6600 | <cmt:alt><cmt:kwd name="-extra_output_suffix" value="extra-output-suffix"/></cmt:alt> |
---|
| 6601 | </cmt:rule> |
---|
| 6602 | <cmt:rule name="library"> |
---|
| 6603 | <cmt:alt> |
---|
| 6604 | <cmt:kwd/> |
---|
| 6605 | <cmt:term name="library-name"/> |
---|
| 6606 | <cmt:optionseq> |
---|
| 6607 | <cmt:ruleref name="constituent-option"/> |
---|
| 6608 | </cmt:optionseq> |
---|
| 6609 | </cmt:alt> |
---|
| 6610 | <cmt:continuation> |
---|
| 6611 | <cmt:optionseq> |
---|
| 6612 | <cmt:ruleref name="source"/> |
---|
| 6613 | </cmt:optionseq> |
---|
| 6614 | </cmt:continuation> |
---|
| 6615 | </cmt:rule> |
---|
| 6616 | <cmt:rule name="macro"> |
---|
| 6617 | <cmt:alt> |
---|
| 6618 | <cmt:kwd/> |
---|
| 6619 | <cmt:term name="macro-name"/> |
---|
| 6620 | <cmt:optionseq> |
---|
| 6621 | <cmt:ruleref name="tag-expr"/> |
---|
| 6622 | <cmt:term name="value"/> |
---|
| 6623 | </cmt:optionseq> |
---|
| 6624 | </cmt:alt> |
---|
| 6625 | </cmt:rule> |
---|
| 6626 | <cmt:rule name="macro_append"> |
---|
| 6627 | <cmt:alt> |
---|
| 6628 | <cmt:kwd/> |
---|
| 6629 | <cmt:term name="macro-name"/> |
---|
| 6630 | <cmt:optionseq> |
---|
| 6631 | <cmt:ruleref name="tag-expr"/> |
---|
| 6632 | <cmt:term name="value"/> |
---|
| 6633 | </cmt:optionseq> |
---|
| 6634 | </cmt:alt> |
---|
| 6635 | </cmt:rule> |
---|
| 6636 | <cmt:rule name="macro_prepend"> |
---|
| 6637 | <cmt:alt> |
---|
| 6638 | <cmt:kwd/> |
---|
| 6639 | <cmt:term name="macro-name"/> |
---|
| 6640 | <cmt:optionseq> |
---|
| 6641 | <cmt:ruleref name="tag-expr"/> |
---|
| 6642 | <cmt:term name="value"/> |
---|
| 6643 | </cmt:optionseq> |
---|
| 6644 | </cmt:alt> |
---|
| 6645 | </cmt:rule> |
---|
| 6646 | <cmt:rule name="macro_remove"> |
---|
| 6647 | <cmt:alt> |
---|
| 6648 | <cmt:kwd/> |
---|
| 6649 | <cmt:term name="macro-name"/> |
---|
| 6650 | <cmt:optionseq> |
---|
| 6651 | <cmt:ruleref name="tag-expr"/> |
---|
| 6652 | <cmt:term name="value"/> |
---|
| 6653 | </cmt:optionseq> |
---|
| 6654 | </cmt:alt> |
---|
| 6655 | </cmt:rule> |
---|
| 6656 | <cmt:rule name="macro_remove_all"> |
---|
| 6657 | <cmt:alt> |
---|
| 6658 | <cmt:kwd/> |
---|
| 6659 | <cmt:term name="macro-name"/> |
---|
| 6660 | <cmt:optionseq> |
---|
| 6661 | <cmt:ruleref name="tag-expr"/> |
---|
| 6662 | <cmt:term name="value"/> |
---|
| 6663 | </cmt:optionseq> |
---|
| 6664 | </cmt:alt> |
---|
| 6665 | </cmt:rule> |
---|
| 6666 | <cmt:rule name="make_fragment"> |
---|
| 6667 | <cmt:alt> |
---|
| 6668 | <cmt:kwd/> |
---|
| 6669 | <cmt:term name="fragment-name"/> |
---|
| 6670 | <cmt:optionseq> |
---|
| 6671 | <cmt:ruleref name="fragment-option"/> |
---|
| 6672 | </cmt:optionseq> |
---|
| 6673 | </cmt:alt> |
---|
| 6674 | </cmt:rule> |
---|
| 6675 | <cmt:rule name="fragment-option"> |
---|
| 6676 | <cmt:alt><cmt:kwd name="-suffix" value="suffix"/></cmt:alt> |
---|
| 6677 | <cmt:alt><cmt:kwd name="-dependencies"/></cmt:alt> |
---|
| 6678 | <cmt:alt><cmt:kwd name="-header" value="fragment"/></cmt:alt> |
---|
| 6679 | <cmt:alt><cmt:kwd name="-trailer" value="fragment"/></cmt:alt> |
---|
| 6680 | </cmt:rule> |
---|
| 6681 | <cmt:rule name="manager"> |
---|
| 6682 | <cmt:alt> |
---|
| 6683 | <cmt:kwd/> |
---|
| 6684 | <cmt:term name="manager-name"/> |
---|
| 6685 | </cmt:alt> |
---|
| 6686 | </cmt:rule> |
---|
| 6687 | <cmt:rule name="package"> |
---|
| 6688 | <cmt:alt> |
---|
| 6689 | <cmt:kwd/> |
---|
| 6690 | <cmt:term name="package-name"/> |
---|
| 6691 | </cmt:alt> |
---|
| 6692 | </cmt:rule> |
---|
| 6693 | <cmt:rule name="path"> |
---|
| 6694 | <cmt:alt> |
---|
| 6695 | <cmt:kwd/> |
---|
| 6696 | <cmt:term name="path-name"/> |
---|
| 6697 | <cmt:optionseq> |
---|
| 6698 | <cmt:ruleref name="tag-expr"/> |
---|
| 6699 | <cmt:term name="value"/> |
---|
| 6700 | </cmt:optionseq> |
---|
| 6701 | </cmt:alt> |
---|
| 6702 | </cmt:rule> |
---|
| 6703 | <cmt:rule name="path_append"> |
---|
| 6704 | <cmt:alt> |
---|
| 6705 | <cmt:kwd/> |
---|
| 6706 | <cmt:term name="path-name"/> |
---|
| 6707 | <cmt:optionseq> |
---|
| 6708 | <cmt:ruleref name="tag-expr"/> |
---|
| 6709 | <cmt:term name="value"/> |
---|
| 6710 | </cmt:optionseq> |
---|
| 6711 | </cmt:alt> |
---|
| 6712 | </cmt:rule> |
---|
| 6713 | <cmt:rule name="path_prepend"> |
---|
| 6714 | <cmt:alt> |
---|
| 6715 | <cmt:kwd/> |
---|
| 6716 | <cmt:term name="path-name"/> |
---|
| 6717 | <cmt:optionseq> |
---|
| 6718 | <cmt:ruleref name="tag-expr"/> |
---|
| 6719 | <cmt:term name="value"/> |
---|
| 6720 | </cmt:optionseq> |
---|
| 6721 | </cmt:alt> |
---|
| 6722 | </cmt:rule> |
---|
| 6723 | <cmt:rule name="path_remove"> |
---|
| 6724 | <cmt:alt> |
---|
| 6725 | <cmt:kwd/> |
---|
| 6726 | <cmt:term name="path-name"/> |
---|
| 6727 | <cmt:optionseq> |
---|
| 6728 | <cmt:ruleref name="tag-expr"/> |
---|
| 6729 | <cmt:term name="value"/> |
---|
| 6730 | </cmt:optionseq> |
---|
| 6731 | </cmt:alt> |
---|
| 6732 | </cmt:rule> |
---|
| 6733 | <cmt:rule name="pattern"> |
---|
| 6734 | <cmt:alt> |
---|
| 6735 | <cmt:kwd/> |
---|
| 6736 | <cmt:option><cmt:kwd name="-global"/></cmt:option> |
---|
| 6737 | <cmt:term name="pattern-name"/> |
---|
| 6738 | <cmt:ruleref name="cmt-statement"/> |
---|
| 6739 | </cmt:alt> |
---|
| 6740 | <cmt:continuation> |
---|
| 6741 | <cmt:optionseq> |
---|
| 6742 | <cmt:kwd name=" ; "/> |
---|
| 6743 | <cmt:ruleref name="cmt-statement"/> |
---|
| 6744 | </cmt:optionseq> |
---|
| 6745 | </cmt:continuation> |
---|
| 6746 | </cmt:rule> |
---|
| 6747 | <cmt:rule name="private"> |
---|
| 6748 | <cmt:alt><cmt:kwd/></cmt:alt> |
---|
| 6749 | </cmt:rule> |
---|
| 6750 | <cmt:rule name="public"> |
---|
| 6751 | <cmt:alt><cmt:kwd/></cmt:alt> |
---|
| 6752 | </cmt:rule> |
---|
| 6753 | <cmt:rule name="set"> |
---|
| 6754 | <cmt:alt> |
---|
| 6755 | <cmt:kwd/> |
---|
| 6756 | <cmt:term name="set-name"/> |
---|
| 6757 | <cmt:optionseq> |
---|
| 6758 | <cmt:ruleref name="tag-expr"/> |
---|
| 6759 | <cmt:term name="value"/> |
---|
| 6760 | </cmt:optionseq> |
---|
| 6761 | </cmt:alt> |
---|
| 6762 | </cmt:rule> |
---|
| 6763 | <cmt:rule name="set_append"> |
---|
| 6764 | <cmt:alt> |
---|
| 6765 | <cmt:kwd/> |
---|
| 6766 | <cmt:term name="set-name"/> |
---|
| 6767 | <cmt:optionseq> |
---|
| 6768 | <cmt:ruleref name="tag-expr"/> |
---|
| 6769 | <cmt:term name="value"/> |
---|
| 6770 | </cmt:optionseq> |
---|
| 6771 | </cmt:alt> |
---|
| 6772 | </cmt:rule> |
---|
| 6773 | <cmt:rule name="set_prepend"> |
---|
| 6774 | <cmt:alt> |
---|
| 6775 | <cmt:kwd/> |
---|
| 6776 | <cmt:term name="set-name"/> |
---|
| 6777 | <cmt:optionseq> |
---|
| 6778 | <cmt:ruleref name="tag-expr"/> |
---|
| 6779 | <cmt:term name="value"/> |
---|
| 6780 | </cmt:optionseq> |
---|
| 6781 | </cmt:alt> |
---|
| 6782 | </cmt:rule> |
---|
| 6783 | <cmt:rule name="set_remove"> |
---|
| 6784 | <cmt:alt> |
---|
| 6785 | <cmt:kwd/> |
---|
| 6786 | <cmt:term name="set-name"/> |
---|
| 6787 | <cmt:optionseq> |
---|
| 6788 | <cmt:ruleref name="tag-expr"/> |
---|
| 6789 | <cmt:term name="value"/> |
---|
| 6790 | </cmt:optionseq> |
---|
| 6791 | </cmt:alt> |
---|
| 6792 | </cmt:rule> |
---|
| 6793 | <cmt:rule name="setup_script"> |
---|
| 6794 | <cmt:alt> |
---|
| 6795 | <cmt:kwd/> |
---|
| 6796 | <cmt:term name="script-name"/> |
---|
| 6797 | </cmt:alt> |
---|
| 6798 | </cmt:rule> |
---|
| 6799 | <cmt:rule name="setup_strategy"> |
---|
| 6800 | <cmt:alt> |
---|
| 6801 | <cmt:kwd/> |
---|
| 6802 | <cmt:term name="setup-strategy-name"/> |
---|
| 6803 | </cmt:alt> |
---|
| 6804 | </cmt:rule> |
---|
| 6805 | <cmt:rule name="setup-strategy-name"> |
---|
| 6806 | <cmt:alt><cmt:kwd name="config"/></cmt:alt> |
---|
| 6807 | <cmt:alt><cmt:kwd name="no_config"/></cmt:alt> |
---|
| 6808 | <cmt:alt><cmt:kwd name="root"/></cmt:alt> |
---|
| 6809 | <cmt:alt><cmt:kwd name="no_root"/></cmt:alt> |
---|
| 6810 | <cmt:alt><cmt:kwd name="cleanup"/></cmt:alt> |
---|
| 6811 | <cmt:alt><cmt:kwd name="no_cleanup"/></cmt:alt> |
---|
| 6812 | </cmt:rule> |
---|
| 6813 | <cmt:rule name="symbol"> |
---|
| 6814 | <cmt:alt><cmt:ruleref name="alias"/></cmt:alt> |
---|
| 6815 | <cmt:alt><cmt:ruleref name="macro"/></cmt:alt> |
---|
| 6816 | <cmt:alt><cmt:ruleref name="macro_append"/></cmt:alt> |
---|
| 6817 | <cmt:alt><cmt:ruleref name="macro_prepend"/></cmt:alt> |
---|
| 6818 | <cmt:alt><cmt:ruleref name="macro_remove"/></cmt:alt> |
---|
| 6819 | <cmt:alt><cmt:ruleref name="macro_remove_all"/></cmt:alt> |
---|
| 6820 | <cmt:alt><cmt:ruleref name="path"/></cmt:alt> |
---|
| 6821 | <cmt:alt><cmt:ruleref name="path_append"/></cmt:alt> |
---|
| 6822 | <cmt:alt><cmt:ruleref name="path_prepend"/></cmt:alt> |
---|
| 6823 | <cmt:alt><cmt:ruleref name="path_remove"/></cmt:alt> |
---|
| 6824 | <cmt:alt><cmt:ruleref name="set"/></cmt:alt> |
---|
| 6825 | <cmt:alt><cmt:ruleref name="set_append"/></cmt:alt> |
---|
| 6826 | <cmt:alt><cmt:ruleref name="set_prepend"/></cmt:alt> |
---|
| 6827 | <cmt:alt><cmt:ruleref name="set_remove"/></cmt:alt> |
---|
| 6828 | </cmt:rule> |
---|
| 6829 | <cmt:rule name="tag"> |
---|
| 6830 | <cmt:alt> |
---|
| 6831 | <cmt:kwd/> |
---|
| 6832 | <cmt:term name="tag-name"/> |
---|
| 6833 | <cmt:optionseq><cmt:term name="tag-name"/></cmt:optionseq> |
---|
| 6834 | </cmt:alt> |
---|
| 6835 | </cmt:rule> |
---|
| 6836 | <cmt:rule name="tag_exclude"> |
---|
| 6837 | <cmt:alt> |
---|
| 6838 | <cmt:kwd/> |
---|
| 6839 | <cmt:term name="tag-name"/> |
---|
| 6840 | <cmt:optionseq><cmt:term name="tag-name"/></cmt:optionseq> |
---|
| 6841 | </cmt:alt> |
---|
| 6842 | </cmt:rule> |
---|
| 6843 | <cmt:rule name="tag-expr"> |
---|
| 6844 | <cmt:alt> |
---|
| 6845 | <cmt:term name="tag-name"/> |
---|
| 6846 | <cmt:optionseq><cmt:kwd name="&"/><cmt:term name="tag-name"/></cmt:optionseq> |
---|
| 6847 | </cmt:alt> |
---|
| 6848 | </cmt:rule> |
---|
| 6849 | <cmt:rule name="use"> |
---|
| 6850 | <cmt:alt> |
---|
| 6851 | <cmt:kwd/> |
---|
| 6852 | <cmt:term name="package-name"/> |
---|
| 6853 | <cmt:option> |
---|
| 6854 | <cmt:ruleref name="version-tag"/> |
---|
| 6855 | <cmt:option> |
---|
| 6856 | <cmt:term name="access-path"/> |
---|
| 6857 | </cmt:option> |
---|
| 6858 | </cmt:option> |
---|
| 6859 | </cmt:alt> |
---|
| 6860 | <cmt:continuation> |
---|
| 6861 | <cmt:option> |
---|
| 6862 | <cmt:ruleref name="use-option"/> |
---|
| 6863 | </cmt:option> |
---|
| 6864 | </cmt:continuation> |
---|
| 6865 | </cmt:rule> |
---|
| 6866 | <cmt:rule name="version"> |
---|
| 6867 | <cmt:alt> |
---|
| 6868 | <cmt:kwd/> |
---|
| 6869 | <cmt:ruleref name="version-tag"/> |
---|
| 6870 | </cmt:alt> |
---|
| 6871 | </cmt:rule> |
---|
| 6872 | <cmt:rule name="version-tag"> |
---|
| 6873 | <cmt:alt> |
---|
| 6874 | <cmt:ruleref name="key"/> |
---|
| 6875 | <cmt:term name="version-number"/> |
---|
| 6876 | </cmt:alt> |
---|
| 6877 | <cmt:continuation> |
---|
| 6878 | <cmt:option> |
---|
| 6879 | <cmt:ruleref name="key"/> |
---|
| 6880 | <cmt:term name="release-number"/> |
---|
| 6881 | <cmt:option> |
---|
| 6882 | <cmt:ruleref name="key"/> |
---|
| 6883 | <cmt:term name="patch-number"/> |
---|
| 6884 | </cmt:option> |
---|
| 6885 | </cmt:option> |
---|
| 6886 | </cmt:continuation> |
---|
| 6887 | </cmt:rule> |
---|
| 6888 | <cmt:rule name="use-option"> |
---|
| 6889 | <cmt:alt><cmt:kwd name="-no_auto_imports"/></cmt:alt> |
---|
| 6890 | <cmt:alt><cmt:kwd name="-auto_imports"/></cmt:alt> |
---|
| 6891 | </cmt:rule> |
---|
| 6892 | <cmt:rule name="key"> |
---|
| 6893 | <cmt:alt><cmt:seq><cmt:term name="letter"/></cmt:seq></cmt:alt> |
---|
| 6894 | </cmt:rule> |
---|
| 6895 | </cmt:syntax> |
---|
| 6896 | |
---|
| 6897 | </cmt:section> |
---|
| 6898 | |
---|
| 6899 | <cmt:section title="The internal mechanism of cmt cvs operations"> |
---|
| 6900 | |
---|
| 6901 | Generally, CVS does not handle queries upon the repository (such as |
---|
| 6902 | knowing all installed modules, all tags of the modules |
---|
| 6903 | etc..). Various tools such as CVSWeb, LXR etc. provide very powerful |
---|
| 6904 | answers to this question, but all through a Web browser. |
---|
| 6905 | |
---|
| 6906 | <p><b>CMT</b> provides a hook that can be installed within a CVS |
---|
| 6907 | repository, based on a helper script that will be activated upon a |
---|
| 6908 | particular CVS command, and that is able to perform some level of |
---|
| 6909 | scan within this repository and return filtered information. </p> |
---|
| 6910 | |
---|
| 6911 | <p>More precisely, this helper script (found in |
---|
| 6912 | <b>${CMTROOT}/mgr/cmt_buildcvsinfos2.sh</b>) is meant to be declared |
---|
| 6913 | within the <b>loginfo</b> management file (see the <a |
---|
| 6914 | href="http://www.cvshome.org/docs/manual/index.html">CVS manual</a> |
---|
| 6915 | for more details) as one entry named <b>.cmtcvsinfos</b>, able to |
---|
| 6916 | launch the helper script. This installation can be operated at once |
---|
| 6917 | using the following sequence:</p> |
---|
| 6918 | |
---|
| 6919 | <cmt:code> |
---|
| 6920 | sh> cd ${CMTROOT}/mgr |
---|
| 6921 | sh> gmake installcvs |
---|
| 6922 | </cmt:code> |
---|
| 6923 | |
---|
| 6924 | <p>This mechanism is thus fully compatible with standard remote |
---|
| 6925 | access to the repository.</p> |
---|
| 6926 | |
---|
| 6927 | <p>Once the helper script is installed, the mechanism operates as |
---|
| 6928 | follows (this actually describes the algorithms installed in the |
---|
| 6929 | <b>CvsImplementation::show_cvs_infos</b> method available in |
---|
| 6930 | <b>cmt_cvs.cxx</b> and is transparently run when one uses the <b>cmt |
---|
| 6931 | cvs<i>xxx</i> commands</b>):</p> |
---|
| 6932 | |
---|
| 6933 | <ol> |
---|
| 6934 | |
---|
| 6935 | <li>Find a location for working with temporary files. This is |
---|
| 6936 | generally deduced from the <b>${TMPDIR}</b> environment variable |
---|
| 6937 | or in <b>/tmp</b> (or in the current directory if none of these |
---|
| 6938 | methods apply).</li> |
---|
| 6939 | |
---|
| 6940 | <li>There, install a directory named |
---|
| 6941 | <b>cmtcvs/<<i>unique-name</i>>/.cmtcvsinfos</b></li> |
---|
| 6942 | |
---|
| 6943 | <li>Then, from this directory, try to run a fake import command |
---|
| 6944 | built as follows: |
---|
| 6945 | |
---|
| 6946 | <cmt:code> |
---|
| 6947 | cvs -Q import -m cmt .cmtcvsinfos/<<i>package-name</i>> CMT v1 |
---|
| 6948 | </cmt:code> |
---|
| 6949 | |
---|
| 6950 | <p>Obviously this command is fake, since no file exist in |
---|
| 6951 | the temporary directory we have just created. However, </p> |
---|
| 6952 | |
---|
| 6953 | </li> |
---|
| 6954 | |
---|
| 6955 | <li>This action actually triggers the |
---|
| 6956 | <b>cmt_buildcvsinfos2.sh</b> script, which simply receives in |
---|
| 6957 | its argument the module name onto which we need |
---|
| 6958 | information. This information is obtained by scanning the |
---|
| 6959 | files into the repository, and an answer is built with the |
---|
| 6960 | following syntax: |
---|
| 6961 | |
---|
| 6962 | <cmt:code> |
---|
| 6963 | [error=<i>error-text</i>] (1) |
---|
| 6964 | tags=<i>tag</i> ... (2) |
---|
| 6965 | branches=<i>branch</i> ... (3) |
---|
| 6966 | subpackages=<i>sub-package</i> ... (4) |
---|
| 6967 | </cmt:code> |
---|
| 6968 | |
---|
| 6969 | <ol> |
---|
| 6970 | |
---|
| 6971 | <li>In case of error (typically when the requested module |
---|
| 6972 | is not found in the repository) a text explaining the |
---|
| 6973 | error condition is returned</li> |
---|
| 6974 | |
---|
| 6975 | <li>The list of tags found on the requirements file</li> |
---|
| 6976 | |
---|
| 6977 | <li>The list of branches defined in this packages (ie |
---|
| 6978 | subdirectories not containing a requirements file)</li> |
---|
| 6979 | |
---|
| 6980 | <li>The list of subpackages (ie subdirectories containing |
---|
| 6981 | a requirements files)</li> |
---|
| 6982 | |
---|
| 6983 | </ol> |
---|
| 6984 | </li> |
---|
| 6985 | </ol> |
---|
| 6986 | |
---|
| 6987 | </cmt:section> |
---|
| 6988 | |
---|
| 6989 | </cmt:section> |
---|
| 6990 | |
---|
| 6991 | </cmt:book> |
---|