loncom/build/readme.html - view

File: [LON-CAPA] / loncom / build / readme.html
Revision 1.22: download - view: text, annotated - select for diffs
Mon Feb 3 18:03:52 2003 UTC (21 years, 3 months ago) by harris41
Branches: MAIN
CVS tags: version_2_9_X, version_2_9_99_0, version_2_9_1, version_2_9_0, version_2_8_X, version_2_8_99_1, version_2_8_99_0, version_2_8_2, version_2_8_1, version_2_8_0, version_2_7_X, version_2_7_99_1, version_2_7_99_0, version_2_7_1, version_2_7_0, version_2_6_X, version_2_6_99_1, version_2_6_99_0, version_2_6_3, version_2_6_2, version_2_6_1, version_2_6_0, version_2_5_X, version_2_5_99_1, version_2_5_99_0, version_2_5_2, version_2_5_1, version_2_5_0, version_2_4_X, version_2_4_99_0, version_2_4_2, version_2_4_1, version_2_4_0, version_2_3_X, version_2_3_99_0, version_2_3_2, version_2_3_1, version_2_3_0, version_2_2_X, version_2_2_99_1, version_2_2_99_0, version_2_2_2, version_2_2_1, version_2_2_0, version_2_1_X, version_2_1_99_3, version_2_1_99_2, version_2_1_99_1, version_2_1_99_0, version_2_1_3, version_2_1_2, version_2_1_1, version_2_1_0, version_2_10_0_RC1, version_2_0_X, version_2_0_99_1, version_2_0_2, version_2_0_1, version_2_0_0, version_1_99_3, version_1_99_2, version_1_99_1_tmcc, version_1_99_1, version_1_99_0_tmcc, version_1_99_0, version_1_3_X, version_1_3_3, version_1_3_2, version_1_3_1, version_1_3_0, version_1_2_X, version_1_2_99_1, version_1_2_99_0, version_1_2_1, version_1_2_0, version_1_1_X, version_1_1_99_5, version_1_1_99_4, version_1_1_99_3, version_1_1_99_2, version_1_1_99_1, version_1_1_99_0, version_1_1_3, version_1_1_2, version_1_1_1, version_1_1_0, version_1_0_99_3, version_1_0_99_2, version_1_0_99_1, version_1_0_99, version_1_0_3, version_1_0_2, version_1_0_1, version_1_0_0, version_0_99_5, version_0_99_4, version_0_99_3, version_0_99_2, version_0_99_1, version_0_99_0, conference_2003, bz6209-base, bz6209, bz5969, bz5610, bz2851, PRINT_INCOMPLETE_base, PRINT_INCOMPLETE, HEAD, GCI_3, GCI_2, GCI_1, BZ5971-printing-apage, BZ5434-fox

best wishes to all.

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