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