Annotation of loncom/build/readme.html, revision 1.22
1.19 harris41 1: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2: "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
1.17 harris41 3: <!-- The LearningOnline Network with CAPA -->
1.22 ! harris41 4: <!-- $Id: readme.html,v 1.21 2002/12/18 17:57:12 harris41 Exp $ -->
1.17 harris41 5: <html>
6: <head>
1.19 harris41 7: <meta http-equiv="Content-Type" content="text/html; charset=utf-8"></meta>
8: <title>LON-CAPA Software Developer Guide</title>
1.17 harris41 9: </head>
10: <body>
1.19 harris41 11: <h1>LON-CAPA Software Developer Guide</h1>
1.17 harris41 12: <p>
1.19 harris41 13: January 17, 2001</i>
1.20 harris41 14: <br /><i>Last updated, August 14, 2002</i>
1.17 harris41 15: </p>
16: <ol>
1.19 harris41 17: <li><a href="#Using_CVS">Using CVS</a>
1.17 harris41 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>
1.19 harris41 26: </ul></li>
1.17 harris41 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>
1.2 harris41 39:
1.17 harris41 40: <ol>
1.19 harris41 41:
42: <li><a name="Using_CVS" /><h2>Using CVS</h2><br />
1.17 harris41 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>
1.19 harris41 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>
1.17 harris41 53: <font color="#008800">
1.19 harris41 54: <tt>export CVSROOT=:pserver:USERNAME@install.lon-capa.org:/home/cvs</tt>
1.17 harris41 55: </font>
56: </p>
57: <p>
58: To actually login, you will need to execute the following command:
1.19 harris41 59: </p>
60: <p>
1.17 harris41 61: <font color="#008800">
1.19 harris41 62: <tt>cvs login</tt>
1.17 harris41 63: </font>
1.19 harris41 64: </p>
65: <p>
66: You are then prompted for a password.
1.17 harris41 67: If you do not have a password, or the password is not working, you
1.19 harris41 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>.)
1.17 harris41 76: </p>
77: <p>
78: <font color="#008800">
1.19 harris41 79: <tt>cvs checkout loncapa</tt><br />
80: <tt>cd loncapa</tt>
1.17 harris41 81: </font>
82: </p>
1.19 harris41 83: <p>After completing work with the CVS repository,
84: you can log out:
85: </p>
86: <p>
1.17 harris41 87: <font color="#008800">
1.19 harris41 88: <tt>cvs logout</tt>
1.17 harris41 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
1.19 harris41 97: other people have made. This is done with the <tt>update</tt> command.
98: </p>
99: <p>
1.17 harris41 100: <font color="#008800">
1.19 harris41 101: <tt>
1.17 harris41 102: cvs update -d
1.19 harris41 103: </tt>
1.17 harris41 104: </font>
105: </p>
106: <p>
1.19 harris41 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>
1.17 harris41 114: <font color="#880000">
1.19 harris41 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>
1.17 harris41 126: `P FILE'
1.19 harris41 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.
1.17 harris41 134: </p>
135: <p>
1.19 harris41 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
1.17 harris41 138: your file with the 'M' flag.
1.19 harris41 139: </p>
140: <p><font color="#880000"><tt>
1.17 harris41 141: `M FILE'
1.19 harris41 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>
1.17 harris41 149: Sometimes, it will occur that:
1.19 harris41 150: </p>
1.17 harris41 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>
1.19 harris41 155: <p>
1.17 harris41 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.
1.19 harris41 159: </p>
160: <p><font color="#880000"><tt>
1.17 harris41 161: `C FILE'
1.19 harris41 162: </tt></font></p>
163: <blockquote><font color="#880000">
1.17 harris41 164: A conflict was detected while trying to merge your changes to FILE
165: with changes from the source repository.
1.19 harris41 166: </font></blockquote>
167: <p>
1.17 harris41 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>
1.19 harris41 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>
1.17 harris41 186: cvs commit
1.19 harris41 187: </tt></font></p>
1.17 harris41 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.)
1.19 harris41 191: </p>
192: <p><font color="#008800"><tt>
1.17 harris41 193: cvs commit FILENAME
1.19 harris41 194: </tt></font></p>
1.17 harris41 195: <p>
1.19 harris41 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
1.17 harris41 199: both short yet uniquely descriptive. For example:
1.19 harris41 200: </p>
1.17 harris41 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>
1.19 harris41 209: <p><font color="#008800"><tt>
1.17 harris41 210: cvs add FILENAME
1.19 harris41 211: </tt></font></p>
1.17 harris41 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>
1.19 harris41 219: <p><font color="#008800"><tt>
1.17 harris41 220: cvs add DIRECTORYNAME
1.19 harris41 221: </tt></font></p>
1.17 harris41 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>
1.19 harris41 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>
1.17 harris41 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>
1.19 harris41 237: Once in a while, multiple programmers may be working on the
1.17 harris41 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>
1.19 harris41 243: If you are absent from programming for a few days, and
1.17 harris41 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>
1.19 harris41 249: </ul></li>
1.17 harris41 250: <li><a name="makeHTML" />
1.19 harris41 251: <h2>Viewing the software (make HTML)</h2>
252: <p>
1.17 harris41 253: <strong>Commands</strong>
1.19 harris41 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>
1.17 harris41 263: <strong>General description of what happens</strong>
1.19 harris41 264: </p>
1.17 harris41 265: <p>
1.6 harris41 266: This is the actual make target code.
1.19 harris41 267: </p>
1.17 harris41 268: <pre>
1.6 harris41 269: <!-- LONCAPA MAKETARGET=HTML START -->
270: HTML:
1.17 harris41 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
1.6 harris41 276: <!-- LONCAPA MAKETARGET=HTML END -->
1.17 harris41 277: </pre>
1.19 harris41 278: <p>
1.7 harris41 279: What basically happens is that specially marked-up data in the LON-CAPA
1.19 harris41 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,
1.7 harris41 283: links, ownerships, permissions, and brief documentation of what each
284: file does.
1.17 harris41 285: </p>
1.19 harris41 286: </li>
1.17 harris41 287: <li><a name="makebuild" />
288: <h2>Compiling the software (make build)</h2>
289: <strong>Commands</strong>
1.19 harris41 290: <p><font color="#008800"><tt>
1.8 harris41 291: cd loncom/build
1.19 harris41 292: <br />make build
293: </tt></font></p>
1.17 harris41 294: <p>
295: <strong>General description of what happens</strong>
296: </p>
297: <p>
1.8 harris41 298: This is the actual make target code.
1.19 harris41 299: </p>
1.17 harris41 300: <pre>
1.13 harris41 301: <!-- LONCAPA MAKETARGET=build START -->
1.17 harris41 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
1.13 harris41 311: <!-- LONCAPA MAKETARGET=build END -->
1.17 harris41 312: </pre>
1.19 harris41 313: <p>
1.17 harris41 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.
1.19 harris41 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).
1.17 harris41 320: </p>
1.19 harris41 321: <p>
1.17 harris41 322: <strong>Example</strong>
1.19 harris41 323: </p>
1.17 harris41 324: <p>
325: Here is information for one file <tt>tth.so</tt> provided in
326: <tt>doc/loncapafiles/loncapafiles.lpml</tt>.
1.19 harris41 327: </p>
1.17 harris41 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>
1.19 harris41 350: <p>
1.17 harris41 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>).
1.19 harris41 360: </p>
1.17 harris41 361: <pre>
1.8 harris41 362: all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so
363:
1.17 harris41 364: ../homework/caparesponse/capa.so: ../homework/caparesponse/caparesponse.c ../homework/caparesponse/caparesponse.pm alwaysrun
1.8 harris41 365: cd ../homework/caparesponse/; sh ./commands
366:
1.17 harris41 367: ../modules/TexConvert/tthperl/tth.so: ../modules/TexConvert/tthperl/../tthdynamic/tthfunc.c ../modules/TexConvert/tthperl/../ttmdynamic/ttmfunc.c
1.8 harris41 368: cd ../modules/TexConvert/tthperl/; sh ./commands
369:
370: alwaysrun:
1.17 harris41 371: </pre>
372: </li><li><a name="loncapafiles" />
1.19 harris41 373: <h2>Adding/removing files from the LON-CAPA installation
374: (doc/loncapafiles/loncapafiles.html)</h2>
375: <p>
1.17 harris41 376: <strong>To add and remove (and alter)</strong>
1.19 harris41 377: </p>
1.17 harris41 378: <p>
1.11 harris41 379: All that you have to do to alter the behavior of the installation is
1.17 harris41 380: edit a single file (<tt>doc/loncapafiles/loncapafiles.lpml</tt>).
1.11 harris41 381: Adding, removing, and altering files requires proper attention
382: to the syntax of file format of course.
1.17 harris41 383: </p>
1.19 harris41 384: <p>
1.17 harris41 385: <strong>File Format</strong>
1.19 harris41 386: </p>
387: <p>
388: The preceding <a href="#makebuild">"make build"</a> documentation
1.17 harris41 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>
1.11 harris41 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.
1.17 harris41 395: </p>
1.19 harris41 396: <p>
1.17 harris41 397: <strong>Philosophy and notes (the thing nobody reads)</strong>
1.19 harris41 398: </p>
1.17 harris41 399: <p>
1.11 harris41 400: Packaging the software from CVS onto a machine file system requires many
401: things:
1.19 harris41 402: </p>
1.17 harris41 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>
1.19 harris41 411: <li>providing for multiple options of installation targets (e.g. RedHat versus
412: Debian),</li>
1.17 harris41 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,
1.19 harris41 424: without having to learn any specifics (or hidden traps) of complicated
425: Makefile's or a new macro language (m4?).</li>
1.17 harris41 426: </ul>
427: <p>
1.11 harris41 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
1.19 harris41 432: whereas we are more concerned with installation parameters). The other
433: alternative, recursive make,
434: has significant deficiencies since not all the information
1.11 harris41 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
1.17 harris41 439: <a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">
1.19 harris41 440: "Recursive Make Considered Harmful" by Peter Miller</a>. Other complications
441: were that, at the time, it was unclear as to what categories
1.11 harris41 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
1.19 harris41 445: as opposed to a per-directory basis.
1.11 harris41 446: Additionally, a standard big Makefile assumes certain "normalcy" to
447: the directory structure of different potential operating system directories
448: (RedHat vs. Debian).
1.17 harris41 449: </p>
450: <p>
1.19 harris41 451: If you take time to look at <tt>loncapafiles.lpml</tt>
1.17 harris41 452: (and perhaps run the <a href="#makeHTML">make HTML</a> command)
1.11 harris41 453: you will find that the organizing information according to the markup
1.17 harris41 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>
1.11 harris41 460: is capable of reading and returning different types of information
1.17 harris41 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
1.11 harris41 463: of error, and has been tested in quite a number of ways. As with
464: any parser however, I remain paranoid.
1.17 harris41 465: </p>
466: <p>
1.19 harris41 467: Finally, some notes on the development.
1.17 harris41 468: <tt>lpml_parse.pl</tt> is very fast and styled after a state-based SAX-like
1.19 harris41 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.
1.17 harris41 477: </p>
478: <p>
479: The <tt>lpml_parse.pl</tt>-<tt>loncapafiles.lpml</tt>
1.19 harris41 480: combination has been highly efficient and error-free.
1.17 harris41 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>
1.12 harris41 488: The current list of configurable files for the LON-CAPA system is
1.19 harris41 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>.
1.17 harris41 497: </p>
498: <p>
1.12 harris41 499: All of these configurable files contain machine-specific information.
1.19 harris41 500: For instance, the overall LON-CAPA system relies on unique host IDs such
1.12 harris41 501: as msua3, s1, s2, msul1, and 103a1 (specified as a "PerlSetVar lonHostID"
1.19 harris41 502: field within <tt>/etc/httpd/conf/loncapa.conf</tt>).
1.12 harris41 503: Non-configurable files simply do NOT have machine-specific information.
1.19 harris41 504: </p>
505: <p>
1.17 harris41 506: <strong>The impact on updating software</strong>
1.19 harris41 507: </p>
1.17 harris41 508: <p>
1.19 harris41 509: What this means in terms of software updating is that:
510: </p>
1.17 harris41 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
1.19 harris41 515: overwritten:
1.17 harris41 516: <ol>
1.19 harris41 517: <li>have their machine-specific information saved,</li>
1.17 harris41 518: <li>be overwritten, and then</li>
1.19 harris41 519: <li>have their machine-specific information restored.</li>
1.17 harris41 520: </ol>
1.19 harris41 521: </li>
1.17 harris41 522: </ul>
1.19 harris41 523: </li>
1.17 harris41 524: <li><a name="makeinstall" />
525: <h2>Updating the non-configurable files on your machine (make install)</h2>
526: <strong>Commands</strong>
1.19 harris41 527: <p><font color="#008800"><tt>
1.13 harris41 528: cd loncom/build
1.19 harris41 529: <br />make install
530: </tt></font></p>
1.17 harris41 531: <p>
532: <strong>General description of what happens</strong>
533: </p>
534: <p>
1.13 harris41 535: This is the actual make target code.
1.19 harris41 536: </p>
1.17 harris41 537: <pre>
1.13 harris41 538: <!-- LONCAPA MAKETARGET=install START -->
1.17 harris41 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
1.13 harris41 555: <!-- LONCAPA MAKETARGET=install END -->
1.17 harris41 556: </pre>
1.19 harris41 557: <p>
558: For safety reasons (so as to preserve a machine's configuration),
1.13 harris41 559: configuration files are NOT installed during this step. This means
1.19 harris41 560: that files such as <tt>/etc/httpd/conf/loncapa.conf</tt>,
561: <tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>, and
1.20 harris41 562: <tt>/home/httpd/spare.tab</tt> are not overwritten, but remain as old,
1.19 harris41 563: non-updated copies. (To automatically update these files and save/restore
1.13 harris41 564: their encoded machine configuration, you must run "make configinstall").
1.17 harris41 565: </p>
1.19 harris41 566: </li>
1.17 harris41 567: <li><a name="makeconfiginstall" />
568: <h2>Updating the configurable files on your machine (make configinstall)</h2>
569: <strong>Commands</strong>
1.19 harris41 570: <p><font color="#008800"><tt>
1.13 harris41 571: cd loncom/build
572: make configinstall
1.19 harris41 573: </tt></font></p>
574: <p>
1.17 harris41 575: <strong>General description of what happens</strong>
1.19 harris41 576: </p>
1.17 harris41 577: <p>
1.13 harris41 578: This is the actual make target code.
1.19 harris41 579: </p>
1.17 harris41 580: <pre>
1.13 harris41 581: <!-- LONCAPA MAKETARGET=configinstall START -->
1.18 harris41 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
1.13 harris41 592: <!-- LONCAPA MAKETARGET=configinstall END -->
1.17 harris41 593: </pre>
1.19 harris41 594: <p>
1.13 harris41 595: Configuration files are installed during this step. This means
1.19 harris41 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,
1.13 harris41 599: a backup copy is made though. Information is read out of these
600: backup copies and restored to the new files by the
1.17 harris41 601: <tt>loncaparestoreconfigurations</tt> script. To ensure that
1.13 harris41 602: new file permissions and ownerships are installed, a final set of
1.17 harris41 603: <tt>chown</tt> and <tt>chmod</tt> commands are called for each of
1.13 harris41 604: the configuration files.
1.17 harris41 605: </p>
606: <p>
607: <strong>For the truly paranoid</strong>
608: </p>
609: <p>
1.13 harris41 610: If you are truly paranoid, you can just make the
1.17 harris41 611: <tt>Makefile.configinstall</tt> file and then save, copy,
1.13 harris41 612: and restore all the configuration values yourself.
1.17 harris41 613: <tt>loncaparestoreconfigurations</tt> is pretty smart though, has yet to
1.19 harris41 614: fail, and besides, when needed, backup copies are made.
1.17 harris41 615: </p>
1.18 harris41 616: </li><li><a name="makeRPM" />
1.17 harris41 617: <h2>Building RPMs (make RPM)</h2>
1.18 harris41 618: <p>
1.19 harris41 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.
1.17 harris41 622: </p>
623: <p>
1.19 harris41 624: <strong>Commands</strong>
1.17 harris41 625: </p>
1.19 harris41 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>
1.17 harris41 633: <p>
634: <strong>Configuration files</strong>
635: </p>
636: <p>
1.13 harris41 637: Configuration files are automatically saved with the file suffix
1.19 harris41 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
1.13 harris41 643: ".rpmsave" files.
1.17 harris41 644: </p>
645: <p>
646: <strong>General description of what happens</strong>
647: </p>
648: <p>
1.13 harris41 649: This is the actual make target code.
1.19 harris41 650: </p>
1.17 harris41 651: <pre>
1.13 harris41 652: <!-- LONCAPA MAKETARGET=RPM START -->
1.17 harris41 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
1.21 harris41 657: cat base_rpm_file_list.txt | perl make_rpm.pl base 3.2 1 '' '' \
1.17 harris41 658: BinaryRoot base_customizerpm.xml
659:
660: BinaryRoot: base_rpm_file_list
661: make TARGET='BinaryRoot' NORESTORECONF='1' install
1.13 harris41 662:
1.17 harris41 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
1.16 harris41 667: <!-- LONCAPA MAKETARGET=RPM END -->
1.17 harris41 668: </pre>
1.19 harris41 669: <p>
1.17 harris41 670: A <tt>BinaryRoot</tt> directory is generated that reflects the locations,
1.13 harris41 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.
1.17 harris41 674: </p>
675: <p>
1.19 harris41 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
1.13 harris41 678: span of months) and, unlike other automated RPM-builders, cleanly
679: builds new RPMs without any after-effect of temporary files left
1.19 harris41 680: on the system. The generated RPM is labeled in the format
1.21 harris41 681: LON-CAPA-base-(VERSION)-(RELEASE).i386. VERSION is specified inside the
1.19 harris41 682: Makefile.
1.17 harris41 683: </p>
1.18 harris41 684: </li>
1.17 harris41 685: </ol>
686: </body>
687: </html>
1.12 harris41 688:
689:
690:
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