Annotation of loncom/build/readme.html, revision 1.18
1.17 harris41 1: <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2: "http://www.w3.org/TR/html4/loose.dtd">
3: <!-- The LearningOnline Network with CAPA -->
1.18 ! harris41 4: <!-- $Id: readme.html,v 1.17 2002/04/27 16:23:40 harris41 Exp $ -->
1.17 harris41 5: <html>
6: <head>
7: <meta name="GENERATOR"
8: content="Scott Harrison and Emacs Version 3.14159265358979" />
9: <title>LON-CAPA Software Developer Instructions</title>
10: </head>
11: <body>
12: <h1>LON-CAPA Software Developer Instructions</h1>
13: <p>
14: <br /><i>Written by Scott Harrison, January 17, 2001</i>
15: <br /><i>Last updated, April 27, 2002</i>
16: </p>
17: <ol>
18: <li><a href="#Using_CVS">Using CVS</a></li>
19: <ul>
20: <li><a href="#cvslog">Logging in and out (cvs login; cvs logout)</a></li>
21: <li><a href="#cvsupdate">Updating files (cvs update -d)</a></li>
22: <li><a href="#cvssave">Saving files (cvs commit)</a></li>
23: <li><a href="#cvsadd">Adding files (cvs add)</a></li>
24: <li><a href="#cvsadddir">Adding directories (cvs add/import)</a></li>
25: <li><a href="#cvsnotsure">What to do when you're not sure about your files
26: (cvs update)</a></li>
27: </ul>
28: <li><a href="#makeHTML">Viewing the software (make HTML)</a></li>
29: <li><a href="#makebuild">Compiling the software (make build)</a></li>
30: <li><a href="#loncapafiles">Adding/removing files from the LON-CAPA
31: installation (doc/loncapafiles/loncapafiles.lpml)</a></li>
32: <li><a href="#configversusnonconfig">Configurable files versus
33: non-configurable files</a></li>
34: <li><a href="#makeinstall">Updating the non-configurable files on your
35: machine (make install)</a></li>
36: <li><a href="#makeconfiginstall">Updating the configurable files on your
37: machine (make configinstall)</a></li>
38: <li><a href="#makeRPM">Building RPMs (make RPM)</a></li>
39: </ol>
1.2 harris41 40:
1.17 harris41 41: <ol>
42: <a name="Using_CVS" />
43: <li><h2>Using CVS</h2></li>
44: These instructions assume that you are using a Linux or UNIX based
45: terminal.
46: <ul>
47: <li><a name="cvslog" />
48: <h3>Using CVS: Logging in and out (cvs login; cvs logout)</h3>
49: <p>
50: To log into CVS, CVS needs to be part of your system environment.
51: You can accomplish this by:
52: <font color="#008800">
53: <pre>
54: export CVSROOT=:pserver:USERNAME@install.lon-capa.org:/home/cvs
55: </pre>
56: </font>
57: </p>
58: <p>
59: To actually login, you will need to execute the following command:
60: <font color="#008800">
61: <pre>
62: cvs login
63: </pre>
64: </font>
65: You will be prompted for a password.
66: If you do not have a password, or the password is not working, you
67: should contact <a href="mailto:helen@lon-capa.org">helen@lon-capa.org</a>
68: </p>
69: <p>
70: If you have yet to check out the CVS repository, you can use the
71: <tt>checkout</tt> command. (Otherwise, just enter your
72: CVS repository, <tt>cd loncapa</tt>.)
73: <font color="#008800">
74: <pre>
75: cvs checkout loncapa
76: cd loncapa
77: </pre>
78: </font>
79: </p>
80: <p>After you have completed your work with the CVS repository, it
81: is recommended that you log out:
82: <font color="#008800">
83: <pre>
84: cvs logout
85: </pre>
86: </font>
87: </p>
88: </li>
89: <li><a name="cvsupdate" />
90: <h3>Using CVS: Updating files (cvs update -d)</h3>
91: <p>
92: After entering your CVS source tree (<tt>cd loncapa</tt>),
93: you should frequently update the software changes that
94: programmers other than yourself have made. This is done
95: with the <tt>update</tt> command.
96: <font color="#008800">
97: <pre>
98: cvs update -d
99: </pre>
100: </font>
101: </p>
102: <p>
103: The <tt>cvs update</tt> command will give you output
104: as it updates your CVS source tree. Commonly you will
105: see 'U' and 'P' which indicate that a file has been updated with
106: changes another programmer has made.
107: <font color="#880000">
108: <pre>
109: `U FILE'
110: The file was brought up to date with respect to the repository.
111: This is done for any file that exists in the repository but not in
112: your source, and for files that you haven't changed but are not
113: the most recent versions available in the repository.
114:
115: `P FILE'
116: Like `U', but the CVS server sends a patch instead of an entire
117: file. These two things accomplish the same thing.
118: </pre>
119: </font>
120: </p>
121: <p>
122: Usually, when you do not <tt>cvs commit</tt> the code changes that you
123: make, the <tt>update</tt> command will tell you that you have modified
124: your file with the 'M' flag.
125: <font color="#880000">
126: <pre>
127: `M FILE'
128: The file is modified in your working directory. This is probably
129: based on changes you made and have not yet "cvs commit"-ed.
130: </pre>
131: </font>
132: Sometimes, it will occur that:
133: <ul>
134: <li>you have modified a file and not yet committed it</li>
135: <li>someone else *has* modified a file and *has* committed it</li>
136: </ul>
137: Generally speaking, this is <strong>your</strong> fault. It is your
138: responsibility to resolve conflicts. <tt>cvs update</tt> informs
139: you of a conflict with the 'C' flag.
140: <font color="#880000">
141: <pre>
142: `C FILE'
143: A conflict was detected while trying to merge your changes to FILE
144: with changes from the source repository.
145: </pre>
146: </font>
147: You will need to open the file and examine it; CVS will have added in
148: markup tags like "<<<<<<" to tell you about the merging
149: conflicts. (Sometimes, CVS will intelligently merge in other changes and
150: give you the 'M' flag, but many times you will have to manually edit
151: the file as just described.)
152: </p>
153: </li>
154: <li><a name="cvssave" />
155: <h3>Using CVS: Saving files (cvs commit)</h3>
156: <p>
157: <tt>cvs commit</tt> works to submit changes to an <strong>existing</strong>
158: file within the repository. If a file does not currently exist, then you
159: will first need to <tt>cvs add</tt> it as described in the following
160: section.
161: </p>
162: Running the <tt>cvs commit</tt> command without passing it an argument will
163: commit all changes that you have within the current directory and
164: subdirectories.
165: <font color="#008800">
166: <pre>
167: cvs commit
168: </pre>
169: </font>
170: </p>
171: <p>
172: A more precise approach to using <tt>cvs commit</tt> is to pass it specific
173: file names. (Usually you should do this.)
174: <font color="#008800">
175: <pre>
176: cvs commit FILENAME
177: </pre>
178: </font>
179: </p>
180: <p>
181: Note that CVS typically invokes the <tt>vi</tt> editor and solicits comments
182: about your latest changes to the software. Your comments should be
183: both short yet uniquely descriptive. For example:
184: <ul>
185: <li><strong>BAD</strong> - "made some changes and am drinking soda"</li>
186: <li><strong>GOOD</strong> - "implemented syntax checking of perl scripts
187: with -c flag"</li>
188: </ul>
189: </p>
190: </li>
191: <li><a name="cvsadd" />
192: <h3>Using CVS: Adding files (cvs add)</h3>
193: <p>
194: <font color="#008800">
195: <pre>
196: cvs add FILENAME
197: </pre>
198: </font>
199: </p>
200: <p>
201: Then you can run <tt>cvs commit FILENAME</tt> and this file will
202: become an "official" part of LON-CAPA.
203: </p>
204: </li>
205: <li><a name="cvsadddir" />
206: <h3>Using CVS: Adding directories (cvs add/import)</h3>
207: <p>
208: <font color="#008800">
209: <pre>
210: cvs add DIRECTORYNAME
211: </pre>
212: </font>
213: </p>
214: <p>
215: There is no need to run <tt>cvs commit</tt>. Directories immediately
216: become part of the LON-CAPA CVS source tree by only using the <tt>cvs add</tt>
217: command.
218: </p>
219: </li>
220: <li><a name="cvsnotsure" />
221: <h3>Using CVS: What to do when you're not sure about your files
222: (cvs update -d)</h3>
223: <p>
224: Every once in a while, multiple programmers may be working on the
225: same file. Most conflicts are avoidable if everybody regularly
226: <strong>commits</strong> their changes AND if everybody
227: regularly <strong>updates</strong> the CVS source tree they are working on.
228: </p>
229: <p>
230: In other words, if you are absent from programming for a few days, and
231: <strong>fail</strong> to run <tt>cvs update -d</tt> on your CVS source
232: repository, you have only yourself to blame if you find yourself writing
233: code in a file that is not up-to-date.
234: </p>
235: </li>
236: </ul>
237: <li><a name="makeHTML" />
238: <h2>Viewing the software (make HTML)</h2></li>
239: <strong>Commands</strong>
240: <font color="#008800">
241: <pre>
1.5 harris41 242: cd loncom/build
1.8 harris41 243: rm -Rf HTML <I>(or alternatively, "make clean")</I>
1.5 harris41 244: make HTML
245: cd HTML
246: <I>(look at the index.html file with a web browser such as Netscape)</I>
1.17 harris41 247: </pre>
248: </font>
249: <strong>General description of what happens</strong>
250: <p>
1.6 harris41 251: This is the actual make target code.
1.17 harris41 252: <font color="#880000">
253: <pre>
1.6 harris41 254: <!-- LONCAPA MAKETARGET=HTML START -->
255: HTML:
1.17 harris41 256: install -d HTML
257: cp $(SOURCE)/doc/loncapafiles/*.gif HTML
258: cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \
259: perl lpml_parse.pl html development default "$(SOURCE)" '$(TARGET)' \
260: > HTML/index.html
1.6 harris41 261: <!-- LONCAPA MAKETARGET=HTML END -->
1.17 harris41 262: </pre>
263: </font>
1.7 harris41 264: What basically happens is that specially marked-up data in the LON-CAPA
1.17 harris41 265: cvs repository file <tt>doc/loncapafiles.lpml</tt> is parsed into a more
266: viewable format by <tt>loncom/build/lpml_parse.pl</tt>. The resulting
1.7 harris41 267: file gives a very well organized view of all the files, directories,
268: links, ownerships, permissions, and brief documentation of what each
269: file does.
1.17 harris41 270: </p>
271: <li><a name="makebuild" />
272: <h2>Compiling the software (make build)</h2>
273: <strong>Commands</strong>
274: <font color="#008800">
275: <pre>
1.8 harris41 276: cd loncom/build
1.9 harris41 277: make build
1.17 harris41 278: </pre>
279: </font>
280: <p>
281: <strong>General description of what happens</strong>
282: </p>
283: <p>
1.8 harris41 284: This is the actual make target code.
1.17 harris41 285: <font color="#880000">
286: <pre>
1.13 harris41 287: <!-- LONCAPA MAKETARGET=build START -->
1.17 harris41 288: build: Makefile.build pod2html.sh pod2man.sh
289: echo -n "" > WARNINGS
290: make -f Makefile.build all
291: make warningnote
292:
293: Makefile.build: $(SOURCE)/doc/loncapafiles/loncapafiles.lpml lpml_parse.pl
294: cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \
295: perl lpml_parse.pl build $(CATEGORY) $(DIST) "$(SOURCE)" "$(TARGET)" \
296: > Makefile.build
1.13 harris41 297: <!-- LONCAPA MAKETARGET=build END -->
1.17 harris41 298: </pre>
299: </font>
300: <tt>loncom/build/lpml_parse.pl</tt> reads in all the build information out
301: of <tt>doc/loncapafiles/loncapafiles.lpml</tt>. A new Makefile named
302: <tt>loncom/build/Makefile.build</tt> is dynamically constructed.
1.8 harris41 303: This dynamically generated Makefile is then run to build/compile
304: all the software targets from source. This currently takes 10 minutes
305: (depends on the speed of the machine you compile with).
1.17 harris41 306: </p>
307: <strong>Example</strong>
308: <p>
309: Here is information for one file <tt>tth.so</tt> provided in
310: <tt>doc/loncapafiles/loncapafiles.lpml</tt>.
311: <font color="#330066">
312: <pre>
313: <file>
314: <source>loncom/homework/caparesponse/capa.so</source>
315: <target dist='default'>usr/lib/perl5/site_perl/5.005/capa.so</target>
316: <target dist='redhat7 redhat7.1'>usr/lib/perl5/site_perl/5.6.0/capa.so</target>
317: <categoryname>system file</categoryname>
318: <description>
319: shared library file for dynamic loading and unloading
320: </description>
321: <build trigger='always run'>
322: loncom/homework/caparesponse/commands
323: </build>
324: <dependencies>
325: caparesponse.c;
326: caparesponse.pm;
327: README;
328: Makefile.PL;
329: capa.i;
330: commands
331: </dependencies>
332: </file>
333: </pre>
334: </font>
335: <tt>loncom/build/lpml_parse.pl</tt> sees the <b>build</b> tags and sets up
336: a dynamic file <tt>Makefile.build</tt> to run the command inside the
337: <b>build</b> tags. The files listed inside the <b>dependencies</b> tags
338: are included in the <tt>Makefile.build</tt> so as to determine whether
339: or not there is a need to compile.
340: </p>
341: <p>
342: Here is an example of a dynamically generated <tt>Makefile.build</tt>
343: that builds two LON-CAPA files (one of which is <tt>tth.so</tt>).
344: <font color="#330066">
345: <pre>
1.8 harris41 346: all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so
347:
1.17 harris41 348: ../homework/caparesponse/capa.so: ../homework/caparesponse/caparesponse.c ../homework/caparesponse/caparesponse.pm alwaysrun
1.8 harris41 349: cd ../homework/caparesponse/; sh ./commands
350:
1.17 harris41 351: ../modules/TexConvert/tthperl/tth.so: ../modules/TexConvert/tthperl/../tthdynamic/tthfunc.c ../modules/TexConvert/tthperl/../ttmdynamic/ttmfunc.c
1.8 harris41 352: cd ../modules/TexConvert/tthperl/; sh ./commands
353:
354: alwaysrun:
1.17 harris41 355: </pre>
356: </font>
357: </p>
358: </li><li><a name="loncapafiles" />
359: <h2>Adding/removing files from the LON-CAPA installation (doc/loncapafiles/loncapafiles.html)</h2>
360: <strong>To add and remove (and alter)</strong>
361: <p>
1.11 harris41 362: All that you have to do to alter the behavior of the installation is
1.17 harris41 363: edit a single file (<tt>doc/loncapafiles/loncapafiles.lpml</tt>).
1.11 harris41 364: Adding, removing, and altering files requires proper attention
365: to the syntax of file format of course.
1.17 harris41 366: </p>
367: <strong>File Format</strong>
1.11 harris41 368: <P>
1.17 harris41 369: The preceding <a href=#"makebuild">"make build"</a> documentation
370: gives an example of a <b>file</b> entry describing one particular file.
371: All data within <tt>loncapafiles.lpml</tt> is specified according
372: to markup tags. The format and syntax of <tt>loncapafiles.lpml</tt>
1.11 harris41 373: is currently best described by the HTML documentation code at the beginning of
374: loncapafiles.html (as well as, by example, seeing how various
375: information is coded). All in all, the syntax is quite simple.
1.17 harris41 376: </p>
377: <strong>Philosophy and notes (the thing nobody reads)</strong>
378: <p>
1.11 harris41 379: Packaging the software from CVS onto a machine file system requires many
380: things:
1.17 harris41 381: <ul>
382: <li>documenting every component of the software,</li>
383: <li>handling CVS <u>source</u> to file system <u>target</u> information,</li>
384: <li>handling (according to a hierarchical scheme of grouping) file
385: ownership and permissions,</li>
386: <li>handling (according to a hierarchical scheme of grouping) directory
387: ownership and permissions,</li>
388: <li>handling symbolic links,</li>
389: <li>providing for multiple options of installation targets
390: (RedHat versus Debian for instance),</li>
391: <li>providing for different file ownerships and permissions to apply
392: to the same file,</li>
393: <li>allowing system software documentation to be automatically generated
394: (see information on <a href="#makeHTML">"make html"</a>),</li>
395: <li>providing information in an easily adjustable form as new demands
396: are made on the software packaging system,</li>
397: <li>providing software package information (for RPM),</li>
398: <li>having information in a format that allows for troubleshooting
399: the current status of the machine file system,</li>
400: <li>allow for changes to the structure of the CVS repository,</li>
401: <li>and something that is simple enough for any one to immediately work with,
1.11 harris41 402: without having to learn specifics (or hidden traps) of complicated Makefile's
1.17 harris41 403: or a new macro language (m4?).</li>
404: </ul>
405: </p>
406: <p>
1.11 harris41 407: I looked into, and tried, different ways of accomplishing the above
408: including automake and recursive make. The automake system seemed quite
409: complicated (and needlessly so in terms of this project since, by and large,
410: it works to coordinate many different types of build/compilation parameters
411: whereas we are more concerned with installation parameters). Recursive make
412: has significant deficiencies in the sense that not all the information
413: is kept in one place, and there are significant levels of dependency
414: between all the things that must be done to keep software packaging
415: up to date. A particularly convincing article I found when looking into
416: much of this was
1.17 harris41 417: <a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">
418: "Recursive Make Considered Harmful" by Peter Miller</a>. Complicating
1.11 harris41 419: matters was, at the time, it was unclear as to what categories
420: of software files we had, and whether or not the directory structure
421: of CVS would remain constant. With an ever-developing directory structure
422: to CVS, I preferred to organize the information on a per-file basis
423: as opposed to a per-directory basis (although there is a successful
1.17 harris41 424: implementation of a standard big Makefile in <tt>loncom/Makefile</tt>).
1.11 harris41 425: Additionally, a standard big Makefile assumes certain "normalcy" to
426: the directory structure of different potential operating system directories
427: (RedHat vs. Debian).
1.17 harris41 428: </p>
429: <p>
430: If you take time to look at loncapafiles.lpml
431: (and perhaps run the <a href="#makeHTML">make HTML</a> command)
1.11 harris41 432: you will find that the organizing information according to the markup
1.17 harris41 433: syntax in <tt>loncapafiles.lpml</tt> is simple. Simple is good.
434: </p>
435: <p>
436: <tt>loncom/build/lpml_parse.pl</tt> is the script (invoked automatically
437: by the various targets in <tt>loncom/build/Makefile</tt>) that reads
438: <tt>doc/loncapafiles/loncapafiles.lpml</tt>. <tt>lpml_parse.pl</tt>
1.11 harris41 439: is capable of reading and returning different types of information
1.17 harris41 440: from <tt>loncapafiles.lpml</tt> depending on how <tt>lpml_parse.pl</tt>
441: is invoked. <tt>lpml_parse.pl</tt> has yet to have introduced new sources
1.11 harris41 442: of error, and has been tested in quite a number of ways. As with
443: any parser however, I remain paranoid.
1.17 harris41 444: </p>
445: <p>
446: <tt>lpml_parse.pl</tt> is very fast and styled after a state-based SAX-like
447: approach. Additionally, <tt>loncapafiles.lpml</tt> has a
448: DTD (loncom/build/lpml.dtd) against which it is valid.
449: I would like to use more ENTITY's inside <tt>lpml.dtd</tt> but currently
450: Perl XML modules available at CPAN do not digest complex ENTITY's that well.
451: </p>
452: <p>
453: The <tt>lpml_parse.pl</tt>-<tt>loncapafiles.lpml</tt>
1.11 harris41 454: combination has been working very efficiently and error-free.
1.17 harris41 455: </p>
456: </li><li><a name="configversusnonconfig" />
457: <h2>Configurable files versus non-configurable files</h2>
458: <p>
459: <strong>Machine-specific information is the difference</strong>
460: </p>
461: <p>
1.12 harris41 462: The current list of configurable files for the LON-CAPA system is
1.13 harris41 463: /etc/httpd/access.conf, /etc/smb.conf, /etc/ntp.conf, /etc/krb.conf,
464: /etc/atalk/config, /etc/ntp/step-tickers,
465: /home/httpd/html/res/adm/includes/copyright.tab,
466: /home/httpd/html/res/adm/includes/un_keyword.tab,
467: /home/httpd/hosts.tab, and
468: /home/httpd/spare.tab.
1.17 harris41 469: </p>
470: <p>
1.12 harris41 471: All of these configurable files contain machine-specific information.
472: For instance, the LON-CAPA system relies on unique host IDs such
473: as msua3, s1, s2, msul1, and 103a1 (specified as a "PerlSetVar lonHostID"
474: field within /etc/httpd/access.conf).
475: Non-configurable files simply do NOT have machine-specific information.
1.17 harris41 476: <strong>The impact on updating software</strong>
477: <p>
1.12 harris41 478: What this means in terms of software updating is that
1.17 harris41 479: <ul>
480: <li>non-configurable files can be simply overwritten with newer versions
481: (without "anything" else to worry about),</li>
482: <li>and configurable files must follow these steps to be safely
483: overwritten</li>
484: <ol>
485: <li>have their machine specific information saved,</li>
486: <li>be overwritten, and then</li>
487: <li>have their machine specific information restored.</li>
488: </ol>
489: </ul>
490: </p>
491: <li><a name="makeinstall" />
492: <h2>Updating the non-configurable files on your machine (make install)</h2>
493: <strong>Commands</strong>
494: <font color="#008800">
495: <pre>
1.13 harris41 496: cd loncom/build
497: make install
1.17 harris41 498: </pre>
499: </font>
500: <p>
501: <strong>General description of what happens</strong>
502: </p>
503: <p>
1.13 harris41 504: This is the actual make target code.
1.17 harris41 505: <font color="#880000">
506: <pre>
1.13 harris41 507: <!-- LONCAPA MAKETARGET=install START -->
1.17 harris41 508: install: TEST_hosts_tab Makefile.install Makefile
509: echo -n "" > WARNINGS
510: make -f Makefile.install SOURCE="$(SOURCE)" TARGET="$(TARGET)" \
511: directories
512: make -f Makefile.install SOURCE="$(SOURCE)" TARGET="$(TARGET)" files
513: make -f Makefile.install SOURCE="$(SOURCE)" TARGET="$(TARGET)" links
514: make SOURCE="$(SOURCE)" TARGET="$(TARGET)" \
515: NORESTORECONF="$(NORESTORECONF)" configinstall
516: make postinstall
517: make warningnote
518: echo "You can run 'make test' to see if your system is ready to go!"
519:
520: Makefile.install: $(SOURCE)/doc/loncapafiles/loncapafiles.lpml lpml_parse.pl
521: cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \
522: perl lpml_parse.pl install $(CATEGORY) $(DIST) "$(SOURCE)" \
523: "$(TARGET)" > Makefile.install
1.13 harris41 524: <!-- LONCAPA MAKETARGET=install END -->
1.17 harris41 525: </pre>
526: </font>
1.13 harris41 527: For safety reasons (so as to not mess up a machine's configuration),
528: configuration files are NOT installed during this step. This means
529: that files such as /etc/httpd/access.conf, /etc/smb.conf, /etc/atalk/config,
530: /home/httpd/html/res/adm/includes/copyright.tab, and
531: /home/httpd/spare.tab are not overwritten, but remain as old, non-updated
532: copies. (To automatically update these files and save/restore
533: their encoded machine configuration, you must run "make configinstall").
1.17 harris41 534: </p>
535: <li><a name="makeconfiginstall" />
536: <h2>Updating the configurable files on your machine (make configinstall)</h2>
537: <strong>Commands</strong>
538: <font color="#008800">
539: <pre>
1.13 harris41 540: cd loncom/build
541: make configinstall
1.17 harris41 542: </pre>
543: </font>
544: <strong>General description of what happens</strong>
545: <p>
1.13 harris41 546: This is the actual make target code.
1.17 harris41 547: <font color="#880000">
548: <pre>
1.13 harris41 549: <!-- LONCAPA MAKETARGET=configinstall START -->
1.18 ! harris41 550: configinstall: Makefile.configinstall
! 551: make -f Makefile.configinstall SOURCE="$(SOURCE)" TARGET="$(TARGET)" \
! 552: configfiles
! 553: if (test "0" = $(NORESTORECONF)); then \
! 554: perl loncaparestoreconfigurations suffix .lpmlnew; fi
! 555:
! 556: Makefile.configinstall: $(SOURCE)/doc/loncapafiles/loncapafiles.lpml lpml_parse.pl
! 557: cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \
! 558: perl lpml_parse.pl configinstall $(CATEGORY) $(DIST) "$(SOURCE)" \
! 559: "$(TARGET)" > Makefile.configinstall
1.13 harris41 560: <!-- LONCAPA MAKETARGET=configinstall END -->
1.17 harris41 561: </pre>
562: </font>
1.13 harris41 563: Configuration files are installed during this step. This means
564: that files such as /etc/httpd/access.conf, /etc/smb.conf, /etc/atalk/config,
565: /home/httpd/html/res/adm/includes/copyright.tab, and
566: /home/httpd/spare.tab are overwritten. Before being overwritten,
567: a backup copy is made though. Information is read out of these
568: backup copies and restored to the new files by the
1.17 harris41 569: <tt>loncaparestoreconfigurations</tt> script. To ensure that
1.13 harris41 570: new file permissions and ownerships are installed, a final set of
1.17 harris41 571: <tt>chown</tt> and <tt>chmod</tt> commands are called for each of
1.13 harris41 572: the configuration files.
1.17 harris41 573: </p>
574: <p>
575: <strong>For the truly paranoid</strong>
576: </p>
577: <p>
1.13 harris41 578: If you are truly paranoid, you can just make the
1.17 harris41 579: <tt>Makefile.configinstall</tt> file and then save, copy,
1.13 harris41 580: and restore all the configuration values yourself.
1.17 harris41 581: <tt>loncaparestoreconfigurations</tt> is pretty smart though, has yet to
582: fail, and besides, when needed backup copies are made.
583: </p>
1.18 ! harris41 584: </li><li><a name="makeRPM" />
1.17 harris41 585: <h2>Building RPMs (make RPM)</h2>
1.18 ! harris41 586: <p>
! 587: LON-CAPA is currently installed through "intelligent tarballs". This
! 588: is part of an earlier (and perhaps future) effort involving RPMs.
1.17 harris41 589: <strong>Commands</strong>
590: <font color="#008800">
591: <pre>
1.13 harris41 592: cd loncom/build
1.16 harris41 593: rm -Rf BinaryRoot <I>(or alternatively, "make clean")</I>
1.13 harris41 594: make RPM
1.16 harris41 595: <I>(to subsequently install, you can type commands like
596: "rpm -Uvh --force LON-CAPA-base-3.1-1.i386.rpm")</I>
1.17 harris41 597: </pre>
598: </font>
599: </p>
600: <strong>WARNING!!!!!!!!!!!!!!</strong>
601: <p>
1.13 harris41 602: Never never never never never manually install the
603: LON-CAPA-setup-3.1-1.i386.rpm. This RPM is meant to only be
604: installed by the CD installation process (it wipes out
605: the existing /etc/passwd file).
1.17 harris41 606: </p>
607: <p>
608: <strong>Configuration files</strong>
609: </p>
610: <p>
1.13 harris41 611: Configuration files are automatically saved with the file suffix
1.17 harris41 612: ".rpmsave". So <tt>/etc/httpd/conf/access.conf</tt> is saved as
613: <tt>/etc/httpd/conf/access.conf.rpmsave</tt>. You can restore
1.13 harris41 614: the machine-specific configuration information by running
1.17 harris41 615: the <tt>/usr/sbin/loncaparestoreconfigurations</tt>. However,
616: a <b>warning</b> is important here. If you install an RPM twice
1.13 harris41 617: without restoring your configuration, you will overwrite the
618: ".rpmsave" files.
1.17 harris41 619: </p>
620: <p>
621: <strong>General description of what happens</strong>
622: </p>
623: <p>
1.13 harris41 624: This is the actual make target code.
1.17 harris41 625: <font color="#880000">
626: <pre>
1.13 harris41 627: <!-- LONCAPA MAKETARGET=RPM START -->
1.17 harris41 628: RPM: BinaryRoot base_rpm_file_list
629: cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \
630: perl lpml_parse.pl make_rpm $(CATEGORY) $(DIST) $(SOURCE) $(TARGET) \
631: > base_customizerpm.xml
632: cat base_rpm_file_list.txt | perl make_rpm.pl base 3.2 '' '' \
633: BinaryRoot base_customizerpm.xml
634:
635: BinaryRoot: base_rpm_file_list
636: make TARGET='BinaryRoot' NORESTORECONF='1' install
1.13 harris41 637:
1.17 harris41 638: base_rpm_file_list:
639: cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \
640: perl lpml_parse.pl rpm_file_list $(CATEGORY) $(DIST) $(SOURCE) \
641: 'BinaryRoot' | sort > base_rpm_file_list.txt
1.16 harris41 642: <!-- LONCAPA MAKETARGET=RPM END -->
1.17 harris41 643: </pre>
644: </font>
645: A <tt>BinaryRoot</tt> directory is generated that reflects the locations,
1.13 harris41 646: ownerships, permissions, and contents for all the CVS source
647: files, compiled binaries, directories, and links as they should eventually
648: occur on the '/' filesystem location.
1.17 harris41 649: </p>
650: <p>
651: <tt>loncom/build/make_rpm.pl</tt> is robust (tested over the
1.13 harris41 652: span of months) and, unlike other automated RPM-builders, cleanly
653: builds new RPMs without any after-effect of temporary files left
654: on the system. (On the negative side, there are a number of
655: LON-CAPA specific customizations inside make_rpm.pl which, for
656: the sake of reusability, should eventually be removed). Two new RPMs
657: are generated: LON-CAPA-base-3.1-1.i386 and LON-CAPA-setup-3.1-1.i386.rpm
658: (again, never manually install LON-CAPA-setup-3.1-1.i386.rpm).
1.17 harris41 659: </p>
1.18 ! harris41 660: </li>
1.17 harris41 661: </ol>
662: </body>
663: </html>
1.12 harris41 664:
665:
666:
667:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to readme.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [LON-CAPA] / loncom / build