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