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