Annotation of loncom/build/readme.html, revision 1.23
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.23 ! raeburn 4: <!-- $Id: readme.html,v 1.22 2003/02/03 18:03:52 harris41 Exp $ -->
! 5: <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
1.17 harris41 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.23 ! raeburn 13: Created: <i>January 17, 2001</i>
! 14: <br />Last updated: <i>January 9, 2011</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>
1.23 ! raeburn 19: <li><a href="#cvslog">Setting up cvs access</a></li>
1.17 harris41 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" />
1.23 ! raeburn 47: <h3>Setting up cvs access</h3>
1.17 harris41 48: <p>
1.23 ! raeburn 49: CVS needs to be part of your system environment in order to access the LON-CAPA CVS repository,
1.19 harris41 50: You can do this by:
51: </p>
52: <p>
1.17 harris41 53: <font color="#008800">
1.23 ! raeburn 54: <tt>export CVS_RSH=ssh</tt><br />
! 55: <tt>export CVSROOT=:ext:USERNAME@source.lon-capa.org:/home/cvs</tt>
1.17 harris41 56: </font>
1.19 harris41 57: </p>
1.23 ! raeburn 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>
1.19 harris41 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>.)
1.17 harris41 72: </p>
73: <p>
74: <font color="#008800">
1.19 harris41 75: <tt>cvs checkout loncapa</tt><br />
76: <tt>cd loncapa</tt>
1.17 harris41 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
1.19 harris41 85: other people have made. This is done with the <tt>update</tt> command.
86: </p>
87: <p>
1.17 harris41 88: <font color="#008800">
1.19 harris41 89: <tt>
1.17 harris41 90: cvs update -d
1.19 harris41 91: </tt>
1.17 harris41 92: </font>
93: </p>
94: <p>
1.19 harris41 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>
1.17 harris41 102: <font color="#880000">
1.19 harris41 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>
1.17 harris41 114: `P FILE'
1.19 harris41 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.
1.17 harris41 122: </p>
123: <p>
1.19 harris41 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
1.17 harris41 126: your file with the 'M' flag.
1.19 harris41 127: </p>
128: <p><font color="#880000"><tt>
1.17 harris41 129: `M FILE'
1.19 harris41 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>
1.17 harris41 137: Sometimes, it will occur that:
1.19 harris41 138: </p>
1.17 harris41 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>
1.19 harris41 143: <p>
1.17 harris41 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.
1.19 harris41 147: </p>
148: <p><font color="#880000"><tt>
1.17 harris41 149: `C FILE'
1.19 harris41 150: </tt></font></p>
151: <blockquote><font color="#880000">
1.17 harris41 152: A conflict was detected while trying to merge your changes to FILE
153: with changes from the source repository.
1.19 harris41 154: </font></blockquote>
155: <p>
1.17 harris41 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>
1.19 harris41 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>
1.17 harris41 174: cvs commit
1.19 harris41 175: </tt></font></p>
1.17 harris41 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.)
1.19 harris41 179: </p>
180: <p><font color="#008800"><tt>
1.17 harris41 181: cvs commit FILENAME
1.19 harris41 182: </tt></font></p>
1.17 harris41 183: <p>
1.19 harris41 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
1.23 ! raeburn 187: descriptive and informative. For example:
1.19 harris41 188: </p>
1.17 harris41 189: <ul>
1.23 ! raeburn 190: <li><strong>BAD</strong> - "saving my work"</li>
1.17 harris41 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>
1.19 harris41 197: <p><font color="#008800"><tt>
1.17 harris41 198: cvs add FILENAME
1.19 harris41 199: </tt></font></p>
1.17 harris41 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>
1.19 harris41 207: <p><font color="#008800"><tt>
1.17 harris41 208: cvs add DIRECTORYNAME
1.19 harris41 209: </tt></font></p>
1.17 harris41 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>
1.19 harris41 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>
1.17 harris41 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>
1.19 harris41 225: Once in a while, multiple programmers may be working on the
1.17 harris41 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>
1.19 harris41 231: If you are absent from programming for a few days, and
1.17 harris41 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>
1.19 harris41 237: </ul></li>
1.17 harris41 238: <li><a name="makeHTML" />
1.19 harris41 239: <h2>Viewing the software (make HTML)</h2>
240: <p>
1.17 harris41 241: <strong>Commands</strong>
1.19 harris41 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>
1.17 harris41 251: <strong>General description of what happens</strong>
1.19 harris41 252: </p>
1.17 harris41 253: <p>
1.6 harris41 254: This is the actual make target code.
1.19 harris41 255: </p>
1.17 harris41 256: <pre>
1.6 harris41 257: <!-- LONCAPA MAKETARGET=HTML START -->
258: HTML:
1.17 harris41 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
1.6 harris41 264: <!-- LONCAPA MAKETARGET=HTML END -->
1.17 harris41 265: </pre>
1.19 harris41 266: <p>
1.7 harris41 267: What basically happens is that specially marked-up data in the LON-CAPA
1.19 harris41 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,
1.7 harris41 271: links, ownerships, permissions, and brief documentation of what each
272: file does.
1.17 harris41 273: </p>
1.19 harris41 274: </li>
1.17 harris41 275: <li><a name="makebuild" />
276: <h2>Compiling the software (make build)</h2>
277: <strong>Commands</strong>
1.19 harris41 278: <p><font color="#008800"><tt>
1.8 harris41 279: cd loncom/build
1.19 harris41 280: <br />make build
281: </tt></font></p>
1.17 harris41 282: <p>
283: <strong>General description of what happens</strong>
284: </p>
285: <p>
1.8 harris41 286: This is the actual make target code.
1.19 harris41 287: </p>
1.17 harris41 288: <pre>
1.13 harris41 289: <!-- LONCAPA MAKETARGET=build START -->
1.17 harris41 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
1.13 harris41 299: <!-- LONCAPA MAKETARGET=build END -->
1.17 harris41 300: </pre>
1.19 harris41 301: <p>
1.17 harris41 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.
1.19 harris41 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).
1.17 harris41 308: </p>
1.19 harris41 309: <p>
1.17 harris41 310: <strong>Example</strong>
1.19 harris41 311: </p>
1.17 harris41 312: <p>
313: Here is information for one file <tt>tth.so</tt> provided in
314: <tt>doc/loncapafiles/loncapafiles.lpml</tt>.
1.19 harris41 315: </p>
1.17 harris41 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>
1.19 harris41 338: <p>
1.17 harris41 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>).
1.19 harris41 348: </p>
1.17 harris41 349: <pre>
1.8 harris41 350: all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so
351:
1.17 harris41 352: ../homework/caparesponse/capa.so: ../homework/caparesponse/caparesponse.c ../homework/caparesponse/caparesponse.pm alwaysrun
1.8 harris41 353: cd ../homework/caparesponse/; sh ./commands
354:
1.17 harris41 355: ../modules/TexConvert/tthperl/tth.so: ../modules/TexConvert/tthperl/../tthdynamic/tthfunc.c ../modules/TexConvert/tthperl/../ttmdynamic/ttmfunc.c
1.8 harris41 356: cd ../modules/TexConvert/tthperl/; sh ./commands
357:
358: alwaysrun:
1.17 harris41 359: </pre>
360: </li><li><a name="loncapafiles" />
1.19 harris41 361: <h2>Adding/removing files from the LON-CAPA installation
362: (doc/loncapafiles/loncapafiles.html)</h2>
363: <p>
1.17 harris41 364: <strong>To add and remove (and alter)</strong>
1.19 harris41 365: </p>
1.17 harris41 366: <p>
1.11 harris41 367: All that you have to do to alter the behavior of the installation is
1.17 harris41 368: edit a single file (<tt>doc/loncapafiles/loncapafiles.lpml</tt>).
1.11 harris41 369: Adding, removing, and altering files requires proper attention
370: to the syntax of file format of course.
1.17 harris41 371: </p>
1.19 harris41 372: <p>
1.17 harris41 373: <strong>File Format</strong>
1.19 harris41 374: </p>
375: <p>
376: The preceding <a href="#makebuild">"make build"</a> documentation
1.17 harris41 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>
1.11 harris41 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.
1.17 harris41 383: </p>
1.19 harris41 384: <p>
1.17 harris41 385: <strong>Philosophy and notes (the thing nobody reads)</strong>
1.19 harris41 386: </p>
1.17 harris41 387: <p>
1.11 harris41 388: Packaging the software from CVS onto a machine file system requires many
389: things:
1.19 harris41 390: </p>
1.17 harris41 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>
1.19 harris41 399: <li>providing for multiple options of installation targets (e.g. RedHat versus
400: Debian),</li>
1.17 harris41 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,
1.19 harris41 412: without having to learn any specifics (or hidden traps) of complicated
413: Makefile's or a new macro language (m4?).</li>
1.17 harris41 414: </ul>
415: <p>
1.11 harris41 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
1.19 harris41 420: whereas we are more concerned with installation parameters). The other
421: alternative, recursive make,
422: has significant deficiencies since not all the information
1.11 harris41 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
1.17 harris41 427: <a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">
1.19 harris41 428: "Recursive Make Considered Harmful" by Peter Miller</a>. Other complications
429: were that, at the time, it was unclear as to what categories
1.11 harris41 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
1.19 harris41 433: as opposed to a per-directory basis.
1.11 harris41 434: Additionally, a standard big Makefile assumes certain "normalcy" to
435: the directory structure of different potential operating system directories
436: (RedHat vs. Debian).
1.17 harris41 437: </p>
438: <p>
1.19 harris41 439: If you take time to look at <tt>loncapafiles.lpml</tt>
1.17 harris41 440: (and perhaps run the <a href="#makeHTML">make HTML</a> command)
1.11 harris41 441: you will find that the organizing information according to the markup
1.17 harris41 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>
1.11 harris41 448: is capable of reading and returning different types of information
1.17 harris41 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
1.11 harris41 451: of error, and has been tested in quite a number of ways. As with
452: any parser however, I remain paranoid.
1.17 harris41 453: </p>
454: <p>
1.19 harris41 455: Finally, some notes on the development.
1.17 harris41 456: <tt>lpml_parse.pl</tt> is very fast and styled after a state-based SAX-like
1.19 harris41 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.
1.17 harris41 465: </p>
466: <p>
467: The <tt>lpml_parse.pl</tt>-<tt>loncapafiles.lpml</tt>
1.19 harris41 468: combination has been highly efficient and error-free.
1.17 harris41 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>
1.12 harris41 476: The current list of configurable files for the LON-CAPA system is
1.19 harris41 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>.
1.17 harris41 485: </p>
486: <p>
1.12 harris41 487: All of these configurable files contain machine-specific information.
1.19 harris41 488: For instance, the overall LON-CAPA system relies on unique host IDs such
1.12 harris41 489: as msua3, s1, s2, msul1, and 103a1 (specified as a "PerlSetVar lonHostID"
1.19 harris41 490: field within <tt>/etc/httpd/conf/loncapa.conf</tt>).
1.12 harris41 491: Non-configurable files simply do NOT have machine-specific information.
1.19 harris41 492: </p>
493: <p>
1.17 harris41 494: <strong>The impact on updating software</strong>
1.19 harris41 495: </p>
1.17 harris41 496: <p>
1.19 harris41 497: What this means in terms of software updating is that:
498: </p>
1.17 harris41 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
1.19 harris41 503: overwritten:
1.17 harris41 504: <ol>
1.19 harris41 505: <li>have their machine-specific information saved,</li>
1.17 harris41 506: <li>be overwritten, and then</li>
1.19 harris41 507: <li>have their machine-specific information restored.</li>
1.17 harris41 508: </ol>
1.19 harris41 509: </li>
1.17 harris41 510: </ul>
1.19 harris41 511: </li>
1.17 harris41 512: <li><a name="makeinstall" />
513: <h2>Updating the non-configurable files on your machine (make install)</h2>
514: <strong>Commands</strong>
1.19 harris41 515: <p><font color="#008800"><tt>
1.13 harris41 516: cd loncom/build
1.19 harris41 517: <br />make install
518: </tt></font></p>
1.17 harris41 519: <p>
520: <strong>General description of what happens</strong>
521: </p>
522: <p>
1.13 harris41 523: This is the actual make target code.
1.19 harris41 524: </p>
1.17 harris41 525: <pre>
1.13 harris41 526: <!-- LONCAPA MAKETARGET=install START -->
1.17 harris41 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
1.13 harris41 543: <!-- LONCAPA MAKETARGET=install END -->
1.17 harris41 544: </pre>
1.19 harris41 545: <p>
546: For safety reasons (so as to preserve a machine's configuration),
1.13 harris41 547: configuration files are NOT installed during this step. This means
1.19 harris41 548: that files such as <tt>/etc/httpd/conf/loncapa.conf</tt>,
549: <tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>, and
1.20 harris41 550: <tt>/home/httpd/spare.tab</tt> are not overwritten, but remain as old,
1.19 harris41 551: non-updated copies. (To automatically update these files and save/restore
1.13 harris41 552: their encoded machine configuration, you must run "make configinstall").
1.17 harris41 553: </p>
1.19 harris41 554: </li>
1.17 harris41 555: <li><a name="makeconfiginstall" />
556: <h2>Updating the configurable files on your machine (make configinstall)</h2>
557: <strong>Commands</strong>
1.19 harris41 558: <p><font color="#008800"><tt>
1.13 harris41 559: cd loncom/build
560: make configinstall
1.19 harris41 561: </tt></font></p>
562: <p>
1.17 harris41 563: <strong>General description of what happens</strong>
1.19 harris41 564: </p>
1.17 harris41 565: <p>
1.13 harris41 566: This is the actual make target code.
1.19 harris41 567: </p>
1.17 harris41 568: <pre>
1.13 harris41 569: <!-- LONCAPA MAKETARGET=configinstall START -->
1.18 harris41 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
1.13 harris41 580: <!-- LONCAPA MAKETARGET=configinstall END -->
1.17 harris41 581: </pre>
1.19 harris41 582: <p>
1.13 harris41 583: Configuration files are installed during this step. This means
1.19 harris41 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,
1.13 harris41 587: a backup copy is made though. Information is read out of these
588: backup copies and restored to the new files by the
1.17 harris41 589: <tt>loncaparestoreconfigurations</tt> script. To ensure that
1.13 harris41 590: new file permissions and ownerships are installed, a final set of
1.17 harris41 591: <tt>chown</tt> and <tt>chmod</tt> commands are called for each of
1.13 harris41 592: the configuration files.
1.17 harris41 593: </p>
594: <p>
595: <strong>For the truly paranoid</strong>
596: </p>
597: <p>
1.13 harris41 598: If you are truly paranoid, you can just make the
1.17 harris41 599: <tt>Makefile.configinstall</tt> file and then save, copy,
1.13 harris41 600: and restore all the configuration values yourself.
1.17 harris41 601: <tt>loncaparestoreconfigurations</tt> is pretty smart though, has yet to
1.19 harris41 602: fail, and besides, when needed, backup copies are made.
1.17 harris41 603: </p>
1.18 harris41 604: </li><li><a name="makeRPM" />
1.17 harris41 605: <h2>Building RPMs (make RPM)</h2>
1.18 harris41 606: <p>
1.19 harris41 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.
1.17 harris41 610: </p>
611: <p>
1.19 harris41 612: <strong>Commands</strong>
1.17 harris41 613: </p>
1.19 harris41 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>
1.17 harris41 621: <p>
622: <strong>Configuration files</strong>
623: </p>
624: <p>
1.13 harris41 625: Configuration files are automatically saved with the file suffix
1.19 harris41 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
1.13 harris41 631: ".rpmsave" files.
1.17 harris41 632: </p>
633: <p>
634: <strong>General description of what happens</strong>
635: </p>
636: <p>
1.13 harris41 637: This is the actual make target code.
1.19 harris41 638: </p>
1.17 harris41 639: <pre>
1.13 harris41 640: <!-- LONCAPA MAKETARGET=RPM START -->
1.17 harris41 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
1.21 harris41 645: cat base_rpm_file_list.txt | perl make_rpm.pl base 3.2 1 '' '' \
1.17 harris41 646: BinaryRoot base_customizerpm.xml
647:
648: BinaryRoot: base_rpm_file_list
649: make TARGET='BinaryRoot' NORESTORECONF='1' install
1.13 harris41 650:
1.17 harris41 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
1.16 harris41 655: <!-- LONCAPA MAKETARGET=RPM END -->
1.17 harris41 656: </pre>
1.19 harris41 657: <p>
1.17 harris41 658: A <tt>BinaryRoot</tt> directory is generated that reflects the locations,
1.13 harris41 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.
1.17 harris41 662: </p>
663: <p>
1.19 harris41 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
1.13 harris41 666: span of months) and, unlike other automated RPM-builders, cleanly
667: builds new RPMs without any after-effect of temporary files left
1.19 harris41 668: on the system. The generated RPM is labeled in the format
1.21 harris41 669: LON-CAPA-base-(VERSION)-(RELEASE).i386. VERSION is specified inside the
1.19 harris41 670: Makefile.
1.17 harris41 671: </p>
1.18 harris41 672: </li>
1.17 harris41 673: </ol>
674: </body>
675: </html>
1.12 harris41 676:
677:
678:
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