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> |
---|