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 | |
---|
12 | Although many major internal evolutions occurred in this version of |
---|
13 | <B>CMT</B>, the primary source of information handled by <B>CMT</B>, |
---|
14 | i.e. the syntax - and semantics - of the <CODE>requirements</CODE> |
---|
15 | file did not change. Therefore we expect that the effects of using |
---|
16 | this new version to a package already managed by previous versions of |
---|
17 | <B>CMT</B>, will remain limited. |
---|
18 | |
---|
19 | <P> |
---|
20 | Generally, it is enough to just <I>re-configure</I> the package, using |
---|
21 | the well known command |
---|
22 | |
---|
23 | <P> |
---|
24 | <CODE> |
---|
25 | > cmt config |
---|
26 | </CODE> |
---|
27 | |
---|
28 | <P>This will result in re-generating the <CODE>setup</CODE> scripts, |
---|
29 | and verifying <CODE>Makefile</CODE>. A proper <B>CMT</B> |
---|
30 | <CODE>Makefile</CODE> now contains at least the two following lines: |
---|
31 | |
---|
32 | <CODE> |
---|
33 | include ${CMTROOT}/src/Makefile.header |
---|
34 | include ${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 |
---|
39 | second one is new. It replaces the former |
---|
40 | |
---|
41 | <CODE> |
---|
42 | include constituents.make |
---|
43 | </CODE> |
---|
44 | |
---|
45 | <P>These two lines are the only required lines to be present in an |
---|
46 | operational <CODE>Makefile</CODE>. However, the user is entirely free |
---|
47 | to install additional make statements at any location for his/her own |
---|
48 | purpose. |
---|
49 | |
---|
50 | <P>No further operation is then needed. All other |
---|
51 | <CODE>makefile</CODE> fragments will be automatically generated at |
---|
52 | make 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 | > gmake configclean |
---|
59 | </CODE> |
---|
60 | |
---|
61 | <P>it might also be useful (if not recommended !) to clean the binary |
---|
62 | directories and rebuild it as follows: |
---|
63 | |
---|
64 | <CODE> |
---|
65 | > gmake config |
---|
66 | > gmake |
---|
67 | </CODE> |
---|
68 | |
---|
69 | <H2>Differences in the syntax of the Unix commands</H2> |
---|
70 | |
---|
71 | The <B>CMT</B> command handler (i.e. the <CODE>cmt</CODE> command) |
---|
72 | received a few modifications but which mainly consisted in removing |
---|
73 | some of the existing options which have been automated. This is the |
---|
74 | case 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 | |
---|
81 | A 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 | |
---|
87 | These scenarios correspond to typical situations a user may encounter |
---|
88 | during his or her development activities. They are presented with |
---|
89 | increasing complexity and will generally refer to each other, avoiding |
---|
90 | some duplication of the explanations. Therefore it is recommended to a |
---|
91 | new user to have a first reading of these sections roughly following |
---|
92 | the order. However, for already experts users it might be appropriate |
---|
93 | to skip some of the first sections (but the section on how to <A |
---|
94 | HREF="#using-CMT">use</A> CMT since this must be understood before any |
---|
95 | other operation described here). |
---|
96 | |
---|
97 | <P> |
---|
98 | <HR> |
---|
99 | <H2><A NAME="BM_using_CMT">Using CMT on Unix</A></H2> |
---|
100 | |
---|
101 | Any user willing to use CMT in a unix environment |
---|
102 | should first setup a few environment variables by <I>sourcing</I> one |
---|
103 | of the appropriate <I>script</I>, according to the shell family (sh or |
---|
104 | csh) the user is considering: |
---|
105 | |
---|
106 | <CODE> |
---|
107 | source /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 |
---|
112 | installed. In the example above, we use the location used at LAL where |
---|
113 | it originates from. In your environment, you will have to ask your |
---|
114 | software manager about the actual CMT location. A typical operation |
---|
115 | then consists in installing this line in the appropriate user's login |
---|
116 | script so as to have CMT automaticly defined at each login session. |
---|
117 | |
---|
118 | <P>(You may also have to understand the CMT <A |
---|
119 | HREF="#installation">installation</A> procedures) |
---|
120 | |
---|
121 | <P> |
---|
122 | <HR> |
---|
123 | <H2>Creating a new test package</H2> |
---|
124 | |
---|
125 | A test package is a very simple unstructured package not meant to be |
---|
126 | exported in any way (ie. not <I>used</I> by any other package). Such a |
---|
127 | package generally corresponds to a simple test application, where the |
---|
128 | developper wants to benefit from the facilities provided by CMT |
---|
129 | (automatization of the building procedure, inheritance of usual |
---|
130 | compilation and linking options, possibility to <I>use</I> other |
---|
131 | structured packages - managed by CMT) while keeping the simplicity of |
---|
132 | an unstructured area, where everything (sources, binaries, etc..) is |
---|
133 | kept in one sigle directory. |
---|
134 | |
---|
135 | <P>Let's consider a simple Fortran application named test made of two |
---|
136 | sources a.f and b.f . The only operation you have to do to build it is |
---|
137 | to create a simpletext file named requirements and containing only one |
---|
138 | line as follows: |
---|
139 | |
---|
140 | <CODE> |
---|
141 | application test a.f b.f |
---|
142 | </CODE> |
---|
143 | |
---|
144 | <P>The very first time you install this test |
---|
145 | package you have to run the installation command: |
---|
146 | |
---|
147 | <CODE> |
---|
148 | cmt config |
---|
149 | </CODE> |
---|
150 | |
---|
151 | Then you can immediately <I>build</I> it as follows: |
---|
152 | |
---|
153 | <CODE> |
---|
154 | gmake |
---|
155 | </CODE> |
---|
156 | |
---|
157 | <P> |
---|
158 | <HR> |
---|
159 | <H2>Creating a new package using the CMT conventions</H2> |
---|
160 | |
---|
161 | A <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 |
---|
164 | thus 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 |
---|
178 | the <CODE>mgr</CODE> and the <CODE>src</CODE> are mandatory. Any other |
---|
179 | set of branch is permitted and can be understood by CMT (typical |
---|
180 | structures elements are the <CODE>doc</CODE> branch, include |
---|
181 | directories named after the package name, alternate source directories |
---|
182 | etc...)</LI> |
---|
183 | |
---|
184 | </OL> |
---|
185 | |
---|
186 | <LI>to provide one text file named <CODE>requirements</CODE> and |
---|
187 | located 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 | > cmt config A v1 |
---|
195 | </CODE> |
---|
196 | |
---|
197 | <P>This installs the minimal structure for the version v1 of the |
---|
198 | package <CODE>A</CODE> below the current directory. This results in |
---|
199 | creating the directory structure (with the <CODE>mgr</CODE> and the |
---|
200 | <CODE>src</CODE> branch), an empty <CODE>requirements</CODE> file and |
---|
201 | a 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>> cd (somewhere)</P> |
---|
206 | <P>> cmt config A v1</P> |
---|
207 | <P>> cd A/v1/mgr</P> |
---|
208 | <P>> vi requirements</P> |
---|
209 | <P>application A a.c b.c</P> |
---|
210 | <P>> vi ../src/a.c</P> |
---|
211 | <P>...</P> |
---|
212 | <P>> vi ../src/b.c</P> |
---|
213 | <P>...</P> |
---|
214 | <P>> gmake</P> |
---|
215 | <P>> ../${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 |
---|
226 | package or a structured one). Defining an application consists in the |
---|
227 | following 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 |
---|
244 | default extension of <B><CODE>.exe</B></CODE>, |
---|
245 | i.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>, |
---|
251 | etc
)</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 |
---|
271 | definitions at make time</P> |
---|
272 | |
---|
273 | <CODE> |
---|
274 | <P>> 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> |
---|
279 | macro 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 |
---|
281 | receive any other definition provided either as arguments to the |
---|
282 | <I>make</I> command or statically within the <CODE>requirements</CODE> |
---|
283 | file</P> |
---|
284 | |
---|
285 | <CODE> |
---|
286 | <P>> gmake A_tag=debug</P> |
---|
287 | </CODE> |
---|
288 | |
---|
289 | <P>or</P> |
---|
290 | |
---|
291 | <P>> 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 |
---|
298 | an application. Here again a name for the constituent will have to be |
---|
299 | carefully chosen since it will be used as a mnemonic for all |
---|
300 | configuration items related to this library. Under Unix, for instance, |
---|
301 | - and for a constituent named A - the library will be named libA.a, |
---|
302 | libA.so or libA.ls according to the style of library (static or |
---|
303 | shared) and the operating system. Under Windows, the library is named |
---|
304 | Alib.lib .Similar make macros are available too for a library (see the |
---|
305 | table showing the standard make macros understood by CMT).</P> |
---|
306 | |
---|
307 | <P>In addition, a specific macro named after the package name and |
---|
308 | suffixed with <I>linkopts (e.g. P_linkopts) </I>provides the exported |
---|
309 | linker options to be applied to any client package. This macro will |
---|
310 | generally 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 |
---|
319 | your site, of if you need a private installation. </P> |
---|
320 | |
---|
321 | <P>The first question you need to answer is the location where to |
---|
322 | install CMT. This location is typically a disk area where most of |
---|
323 | packages managed in your project will be located. </P> |
---|
324 | |
---|
325 | <P>Then, you have to fetch the distribution kit from the Web at <A |
---|
326 | HREF="http://www.lal.in2p3.fr/SI/CMT/CMT.htm">http://www.lal.in2p3.fr/SI/CMT/CMT.htm</A>. You |
---|
327 | must get at least the primary distribution kit containing the basic |
---|
328 | configuration information and the CMT sources. This operation results |
---|
329 | in a set of directories hanging below the CMT root and the version |
---|
330 | directory. The src branch contains the sources of CMT, the fragments |
---|
331 | branch contains the makefile fragments and the mgr branch contains the |
---|
332 | scripts needed to build or operate CMT. </P> |
---|
333 | |
---|
334 | <P>The very first operation after dowloading CMT consists in running |
---|
335 | the INSTALL shell script. This will build the setup scripts required |
---|
336 | by any CMT user. </P> |
---|
337 | |
---|
338 | <P>Then you may either decide to build CMT by yourself or fetch a |
---|
339 | pre-built binary from the same Web location. The prebuilt binary |
---|
340 | versions may not exist for the actual plateform you are working |
---|
341 | on. You will see on the distribution page the precise configurations |
---|
342 | used for building those binaries. </P> |
---|
343 | |
---|
344 | <P>In case you have to build CMT yourself, you need a C++ compiler |
---|
345 | capable of handling templates (although the support for STL is not |
---|
346 | required). Their is a Makefile provided in the distribution kit which |
---|
347 | takes g++ by default as the compiler. If you need a specific C++ |
---|
348 | compiler 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 |
---|
357 | plateform. CMT builds a configuration tag per each type of plateform, |
---|
358 | and uses this tag for naming the directory where all binary files will |
---|
359 | be stored. As such this tag has to be defined prior to even build CMT |
---|
360 | itself. </P> |
---|
361 | |
---|
362 | <P>CMT builds the default configuration by running the cmt_system.sh |
---|
363 | script found in the mgr branch of CMT. Run it manually to see what is |
---|
364 | the default value provided by this script. You might consider changing |
---|
365 | its 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 |
---|
370 | your site, of if you need a private installation. </P> |
---|
371 | |
---|
372 | <P>The first question you need to answer is the location where to |
---|
373 | install CMT. This location is typically a disk area where most of |
---|
374 | packages managed in your project will be located. </P> |
---|
375 | |
---|
376 | <P>Then, you have to fetch the distribution kit from the Web at <A |
---|
377 | HREF="http://www.lal.in2p3.fr/SI/CMT/CMT.htm">http://www.lal.in2p3.fr/SI/CMT/CMT.htm</A>. You |
---|
378 | must get at least the primary distribution kit containing the basic |
---|
379 | configuration information and the CMT sources. This operation results |
---|
380 | in a set of directories hanging below the CMT root and the version |
---|
381 | directory. The binary kit provided for Windows environments will |
---|
382 | generally fit your needs. </P> |
---|
383 | |
---|
384 | <P>The next operation consists in defining a few registries (typically |
---|
385 | using the standard RegEdit facility): </P> |
---|
386 | |
---|
387 | <UL> |
---|
388 | |
---|
389 | <LI>HKEY_CLASSES_ROOT/Software/CMT/root will contain the root |
---|
390 | directory where CMT is installed (eg. "e:"). </LI> |
---|
391 | |
---|
392 | <LI>HKEY_CLASSES_ROOT/Software/CMT/version will contain the current |
---|
393 | version tag of CMT ("v1r3" for this version). </LI> |
---|
394 | |
---|
395 | <LI>HKEY_CLASSES_ROOT/Software/CMT/path/ may optionally contain a set |
---|
396 | of text values corresponding to the different package global access |
---|
397 | paths. </LI> |
---|
398 | |
---|
399 | <LI>HKEY_CURRENT_USER/Software/CMT/path/ may contain a set of text of |
---|
400 | text values corresponding to the different package private access |
---|
401 | paths. </LI></UL> |
---|
402 | |
---|
403 | </BODY> |
---|
404 | </HTML> |
---|