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