source: CMT/v1r10p20011126/doc/CMTDoc2.html @ 1

Last change on this file since 1 was 1, checked in by arnault, 19 years ago

Import all tags
File size: 14.6 KB
Line 
1<HTML>
2<HEAD>
3</HEAD>
4<BODY>
5
6<P>
7<HR>
8<H1>Differences with previous versions of CMT</H1>
9
10<H2>Converting a package that was managed with previous versions of CMT (or methods)</H2>
11
12Although many major internal evolutions occurred in this version of
13<B>CMT</B>, the primary source of information handled by <B>CMT</B>,
14i.e. the syntax - and semantics - of the <CODE>requirements</CODE>
15file did not change. Therefore we expect that the effects of using
16this new version to a package already managed by previous versions of
17<B>CMT</B>, will remain limited.
18
19<P>
20Generally, it is enough to just <I>re-configure</I> the package, using
21the well known command
22
23<P>
24<CODE>
25&gt; cmt config
26</CODE>
27
28<P>This will result in re-generating the <CODE>setup</CODE> scripts,
29and verifying <CODE>Makefile</CODE>. A proper <B>CMT</B>
30<CODE>Makefile</CODE> now contains at least the two following lines:
31
32<CODE>
33include ${CMTROOT}/src/Makefile.header
34include ${CMTROOT}/src/constituents.make
35</CODE>
36
37<P>The first one was already generally present in
38<CODE>Makefiles</CODE> used in previous versions of <B>CMT</B> and the
39second one is new. It replaces the former
40
41<CODE>
42include constituents.make
43</CODE>
44
45<P>These two lines are the only required lines to be present in an
46operational <CODE>Makefile</CODE>. However, the user is entirely free
47to install additional make statements at any location for his/her own
48purpose.
49
50<P>No further operation is then needed. All other
51<CODE>makefile</CODE> fragments will be automatically generated at
52make time. It is even recommended to remove any existing
53<CODE>makefile</CODE> fragment generated by previous versions of
54<B>CMT</B>. This can be easily done by using the dedicated
55<CODE>configclean</CODE> target as follows
56
57<CODE>
58&gt; gmake configclean
59</CODE>
60
61<P>it might also be useful (if not recommended !) to clean the binary
62directories and rebuild it as follows:
63
64<CODE>
65&gt; gmake config
66&gt; gmake
67</CODE>
68
69<H2>Differences in the syntax of the Unix commands</H2>
70
71The <B>CMT</B> command handler (i.e. the <CODE>cmt</CODE> command)
72received a few modifications but which mainly consisted in removing
73some of the existing options which have been automated. This is the
74case for the <CODE>genmake</CODE> command since now,
75<CODE>Makefile</CODE> generation is automatic and transparent..
76
77<P>The <CODE>show</CODE> options are unchanged.
78
79<H2>Operations in a Windows environment</H2>
80
81A graphical and interactive application (<CODE>cmtw</CODE>) is now provided on Windows (95/98/NT) environments. This application permits to browse package directories, to select any version of any package. Its configuration is shown, and interactive edition is possible on its requirements file. A few operations are also possible, such as the generation of MSDev configuration files, so as to permit to directly work of packages managed by <B>CMT</B> with the MSDev development environment. Currently this support is still evolving and user might see limitations in the dialog between CMT and MSDev (only the constituent definitions - applications and libraries - and the use mechanism - package relationships - are understood in the context of MSDev). Users of these new facilities are kindly invited to send their comments, bug observations, suggestions or even contributions to the author.
82
83<P>
84<HR>
85<H1>Some scenarios</H1>
86
87These scenarios correspond to typical situations a user may encounter
88during his or her development activities. They are presented with
89increasing complexity and will generally refer to each other, avoiding
90some duplication of the explanations. Therefore it is recommended to a
91new user to have a first reading of these sections roughly following
92the order. However, for already experts users it might be appropriate
93to skip some of the first sections (but the section on how to <A
94HREF="#using-CMT">use</A> CMT since this must be understood before any
95other operation described here).
96
97<P>
98<HR>
99<H2><A NAME="BM_using_CMT">Using CMT on Unix</A></H2>
100
101Any user willing to use CMT in a unix environment
102should first setup a few environment variables by <I>sourcing</I> one
103of the appropriate <I>script</I>, according to the shell family (sh or
104csh) the user is considering:
105
106<CODE>
107source /lal/CMT/v1r3/mgr/setup.csh
108. /lal/CMT/v1r3/mgr/setup.sh
109</CODE>
110
111<P>Of course, the user has to precisely know where CMT is
112installed. In the example above, we use the location used at LAL where
113it originates from. In your environment, you will have to ask your
114software manager about the actual CMT location. A typical operation
115then consists in installing this line in the appropriate user's login
116script so as to have CMT automaticly defined at each login session.
117
118<P>(You may also have to understand the CMT <A
119HREF="#installation">installation</A> procedures)
120
121<P>
122<HR>
123<H2>Creating a new test package</H2> 
124
125A test package is a very simple unstructured package not meant to be
126exported in any way (ie. not <I>used</I> by any other package). Such a
127package generally corresponds to a simple test application, where the
128developper wants to benefit from the facilities provided by CMT
129(automatization of the building procedure, inheritance of usual
130compilation and linking options, possibility to <I>use</I> other
131structured packages - managed by CMT) while keeping the simplicity of
132an unstructured area, where everything (sources, binaries, etc..) is
133kept in one sigle directory.
134
135<P>Let's consider a simple Fortran application named test made of two
136sources a.f and b.f . The only operation you have to do to build it is
137to create a simpletext file named requirements and containing only one
138line as follows:
139
140<CODE>
141application test a.f b.f
142</CODE>
143
144<P>The very first time you install this test
145package you have to run the installation command:
146
147<CODE>
148cmt config
149</CODE>
150
151Then you can immediately <I>build</I> it as follows:
152
153<CODE>
154gmake
155</CODE>
156
157<P>
158<HR>
159<H2>Creating a new package using the CMT conventions</H2> 
160
161A <B>CMT</B> package is a package able to both use other
162<B>CMT</B>-managed packages and be used by other packages. The
163<I>only</I> constraints for packages to be fully managed by CMT and
164thus subject to <I>use</I>-relationships to each other are:
165
166</P>
167<OL>
168
169<LI>to be installed in the conventional minimal structure at least composed of:</LI>
170
171<OL>
172
173<LI>a <I>root</I> directory named with the package name</LI>
174
175<LI>a <I>version</I> directory immediately below the root directory</LI>
176
177<LI>some <I>branches</I> below the version directory, among which only
178the <CODE>mgr</CODE> and the <CODE>src</CODE> are mandatory. Any other
179set of branch is permitted and can be understood by CMT (typical
180structures elements are the <CODE>doc</CODE> branch, include
181directories named after the package name, alternate source directories
182etc...)</LI>
183
184</OL>
185
186<LI>to provide one text file named <CODE>requirements</CODE> and
187located in its <CODE>mgr</CODE> branch.</LI>
188
189</OL>
190
191<P>These conventions are easily applied if one creates the package using the parameterised <I>config</I> option of CMT as follows:
192
193<CODE>
194&gt; cmt config A v1
195</CODE>
196
197<P>This installs the minimal structure for the version v1 of the
198package <CODE>A</CODE> below the current directory. This results in
199creating the directory structure (with the <CODE>mgr</CODE> and the
200<CODE>src</CODE> branch), an empty <CODE>requirements</CODE> file and
201a minimal <CODE>Makefile</CODE> (both in the <CODE>mgr</CODE> branch).
202
203<P>A complete sequence resulting in a working application could be:
204<CODE>
205<P>&gt; cd (somewhere)</P>
206<P>&gt; cmt config A v1</P>
207<P>&gt; cd A/v1/mgr</P>
208<P>&gt; vi requirements</P>
209<P>application A a.c b.c</P>
210<P>&gt; vi ../src/a.c</P>
211<P>...</P>
212<P>&gt; vi ../src/b.c</P>
213<P>...</P>
214<P>&gt; gmake</P>
215<P>&gt; ../${CMTCONFIG}/A.exe</P>
216</CODE>
217
218<P>Next sections will present more complex examples of how to build libraries or complex applications.</P>
219
220<P>
221<HR>
222</P>
223<H2>Defining a new application</H2>
224
225<P>We are now working in an installed package (which could be a test
226package or a structured one). Defining an application consists in the
227following operations:</P>
228
229<OL>
230<OL>
231
232<LI>Selecting a name (e.g. <B>A</B>) for the application. This name will be used in many places as a mnemonic for the application,</LI>
233
234</OL>
235</OL>
236
237
238<UL>
239<UL>
240
241<LI>it defines the constituent name,</LI>
242
243<LI>it is the file name of the application's executable (with a
244default extension of <B><CODE>.exe</B></CODE>,
245i.e. <B><CODE>A.exe</B></CODE>), </LI>
246
247<LI>it yields a dedicated <I>target</I> of the <CODE>Makefile</CODE>,</LI>
248
249<LI>and it is used as a prefix for various <I>Make</I> macros (such as
250<B><CODE>A_cppflags</B></CODE>, <B><CODE>A_linkflags</B></CODE>,
251etc…)</LI>
252
253</UL>
254</UL>
255
256<OL>
257<OL>
258
259<LI>Installing its definition in the requirements, providing the list of its private source files</LI>
260
261<P>application A a1.c a2.c a3.cxx ../B/*.cxx</P>
262
263<LI>Possibly adding some make macro definitions, specific to this application, still in the requirements file</LI>
264
265</OL>
266</OL>
267
268<P>macro A_cppflags " -g "</P>
269
270<P>Building the application is then entirely deduced from these
271definitions at make time</P>
272
273<CODE>
274<P>&gt; gmake</P>
275</CODE>
276
277<P>And the executable is by default built into
278<B><CODE>../${A_tag}/A.exe</B></CODE> .The <B><CODE>A_tag</B></CODE>
279macro gets the default value of <B><CODE>${CMTCONFIG}</B></CODE>
280(which is always built when <B>CMT</B> is originally set up) but can
281receive any other definition provided either as arguments to the
282<I>make</I> command or statically within the <CODE>requirements</CODE>
283file</P>
284
285<CODE>
286<P>&gt; gmake A_tag=debug</P>
287</CODE>
288
289<P>or</P>
290
291<P>&gt; macro A_tag "debug"</P>
292
293<P><HR></P>
294
295<H2>Defining a new library</H2>
296
297<P>This operation is quite similar to the one described for defining
298an application. Here again a name for the constituent will have to be
299carefully chosen since it will be used as a mnemonic for all
300configuration items related to this library. Under Unix, for instance,
301- and for a constituent named A - the library will be named libA.a,
302libA.so or libA.ls according to the style of library (static or
303shared) and the operating system. Under Windows, the library is named
304Alib.lib .Similar make macros are available too for a library (see the
305table showing the standard make macros understood by CMT).</P>
306
307<P>In addition, a specific macro named after the package name and
308suffixed with <I>linkopts (e.g. P_linkopts) </I>provides the exported
309linker options to be applied to any client package. This macro will
310generally include a set of -L and -l options under Unix.</P>
311
312<P><HR></P>
313
314<H2><A NAME="BM_installation">Installing CMT for the first time</A></H2>
315
316<H3>Installing CMT on your Unix site</H3>
317
318<P>This section is of interest only if CMT is not yet installed on
319your site, of if you need a private installation. </P>
320
321<P>The first question you need to answer is the location where to
322install CMT. This location is typically a disk area where most of
323packages managed in your project will be located. </P>
324
325<P>Then, you have to fetch the distribution kit from the Web at <A
326HREF="http://www.lal.in2p3.fr/SI/CMT/CMT.htm">http://www.lal.in2p3.fr/SI/CMT/CMT.htm</A>. You
327must get at least the primary distribution kit containing the basic
328configuration information and the CMT sources. This operation results
329in a set of directories hanging below the CMT root and the version
330directory. The src branch contains the sources of CMT, the fragments
331branch contains the makefile fragments and the mgr branch contains the
332scripts needed to build or operate CMT. </P>
333
334<P>The very first operation after dowloading CMT consists in running
335the INSTALL shell script. This will build the setup scripts required
336by any CMT user. </P>
337
338<P>Then you may either decide to build CMT by yourself or fetch a
339pre-built binary from the same Web location. The prebuilt binary
340versions may not exist for the actual plateform you are working
341on. You will see on the distribution page the precise configurations
342used for building those binaries. </P>
343
344<P>In case you have to build CMT yourself, you need a C++ compiler
345capable of handling templates (although the support for STL is not
346required). Their is a Makefile provided in the distribution kit which
347takes g++ by default as the compiler. If you need a specific C++
348compiler you will override the cpp macro as follows: </P>
349
350<CODE>
351<P>gmake cpp=CC </P>
352</CODE>
353
354<P>The cppflags macro permits too to override behaviour of the compilation. </P>
355
356<P>Another important concern is the way CMT will identify the
357plateform. CMT builds a configuration tag per each type of plateform,
358and uses this tag for naming the directory where all binary files will
359be stored. As such this tag has to be defined prior to even build CMT
360itself. </P>
361
362<P>CMT builds the default configuration by running the cmt_system.sh
363script found in the mgr branch of CMT. Run it manually to see what is
364the default value provided by this script. You might consider changing
365its algorithm for your own convenience. </P>
366
367<H3>Installing CMT on a Windows or Windows NT site</H3>
368
369<P>This section is of interest only if CMT is not yet installed on
370your site, of if you need a private installation. </P>
371
372<P>The first question you need to answer is the location where to
373install CMT. This location is typically a disk area where most of
374packages managed in your project will be located. </P>
375
376<P>Then, you have to fetch the distribution kit from the Web at <A
377HREF="http://www.lal.in2p3.fr/SI/CMT/CMT.htm">http://www.lal.in2p3.fr/SI/CMT/CMT.htm</A>. You
378must get at least the primary distribution kit containing the basic
379configuration information and the CMT sources. This operation results
380in a set of directories hanging below the CMT root and the version
381directory. The binary kit provided for Windows environments will
382generally fit your needs. </P>
383
384<P>The next operation consists in defining a few registries (typically
385using the standard RegEdit facility): </P>
386
387<UL>
388
389<LI>HKEY_CLASSES_ROOT/Software/CMT/root will contain the root
390directory where CMT is installed (eg. "e:"). </LI>
391
392<LI>HKEY_CLASSES_ROOT/Software/CMT/version will contain the current
393version tag of CMT ("v1r3" for this version). </LI>
394
395<LI>HKEY_CLASSES_ROOT/Software/CMT/path/ may optionally contain a set
396of text values corresponding to the different package global access
397paths. </LI>
398
399<LI>HKEY_CURRENT_USER/Software/CMT/path/ may contain a set of text of
400text values corresponding to the different package private access
401paths. </LI></UL>
402
403</BODY>
404</HTML>
Note: See TracBrowser for help on using the repository browser.