loncom/build/readme.html - view

File: [LON-CAPA] / loncom / build / readme.html
Revision 1.24: download - view: text, annotated - select for diffs
Tue Mar 1 03:43:32 2011 UTC (13 years, 2 months ago) by raeburn
Branches: MAIN
CVS tags: version_2_12_X, version_2_11_X, version_2_11_4_uiuc, version_2_11_4_msu, version_2_11_4, version_2_11_3_uiuc, version_2_11_3_msu, version_2_11_3, version_2_11_2_uiuc, version_2_11_2_msu, version_2_11_2_educog, version_2_11_2, version_2_11_1, version_2_11_0_RC3, version_2_11_0_RC2, version_2_11_0_RC1, version_2_11_0, version_2_10_X, version_2_10_1, version_2_10_0, loncapaMITrelate_1, language_hyphenation_merge, language_hyphenation, HEAD, BZ4492-merge, BZ4492-feature_horizontal_radioresponse, BZ4492-feature_Support_horizontal_radioresponse, BZ4492-Support_horizontal_radioresponse

- Updated with entry for make aboutVERSION.

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 xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> 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: Created: January 17, 2001 14: Last updated: February 28, 2011 15: 16: <ol> 17: <li><a href="#Using_CVS">Using CVS</a> 18: <ul> 19: <li><a href="#cvslog">Setting up cvs access</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="#makeaboutVERSION">Updating the LON-CAPA Version number</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> 40: 41: <ol> 42: 43: <li><a name="Using_CVS" /><h2>Using CVS</h2> 44: These instructions assume that you are using a Linux or UNIX based 45: terminal. 46: <ul> 47: <li><a name="cvslog" /> 48: <h3>Setting up cvs access</h3> 49: 50: CVS needs to be part of your system environment in order to access the LON-CAPA CVS repository, 51: You can do this by: 52: 53: 54: 55: <tt>export CVS_RSH=ssh</tt> 56: <tt>export CVSROOT=:ext:USERNAME@source.lon-capa.org:/home/cvs</tt> 57: 58: 59: 60: To actually issue CVS commands you will need to: 61: 62: <ol> 63: <li>Have installed the CVS client, e.g., <tt>yum install cvs</tt></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 <tt>ssh-keygen -t dsa</tt> and sent the public key to the LON-CAPA helpdesk for installation on the CVS server.</li> 66: </ol> 67: 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>.) 73: 74: 75: 76: <tt>cvs checkout loncapa</tt> 77: <tt>cd loncapa</tt> 78: 79: 80: </li> 81: <li><a name="cvsupdate" /> 82: <h3>Using CVS: Updating files (cvs update -d)</h3> 83: 84: After entering your CVS source tree (<tt>cd loncapa</tt>), 85: you should frequently update the software changes that 86: other people have made. This is done with the <tt>update</tt> command. 87: 88: 89: 90: <tt> 91: cvs update -d 92: </tt> 93: 94: 95: 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: 102: 103: 104: <tt>`U FILE'</tt> 105: <blockquote> 106: The file was brought up to date in your <tt>loncapa</tt>. 107: 'U' is done for: 108: * any file that exists in the repository but not in your source, and 109: * files that you have not changed but are not the most recent versions 110: available in the repository. 111: The network behavior of 'U' is that the entire new file is uploaded 112: from the CVS server. 113: </blockquote> 114: <tt> 115: `P FILE' 116: </tt> 117: <blockquote> 118: Like `U', but the CVS server sends a patch instead of an entire file. 119: </blockquote> 120: 121: 'U' and 'P' essentially accomplish the same thing, just in 122: different ways. 123: 124: 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 127: your file with the 'M' flag. 128: 129: <tt> 130: `M FILE' 131: </tt> 132: <blockquote> 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: </blockquote> 137: 138: Sometimes, it will occur that: 139: 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> 144: 145: Generally speaking, this is your fault. It is your 146: responsibility to resolve conflicts. <tt>cvs update</tt> informs 147: you of a conflict with the 'C' flag. 148: 149: <tt> 150: `C FILE' 151: </tt> 152: <blockquote> 153: A conflict was detected while trying to merge your changes to FILE 154: with changes from the source repository. 155: </blockquote> 156: 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: 163: </li> 164: <li><a name="cvssave" /> 165: <h3>Using CVS: Saving files (cvs commit)</h3> 166: 167: <tt>cvs commit</tt> works to submit changes to an existing 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: 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: <tt> 175: cvs commit 176: </tt> 177: 178: A more precise approach to using <tt>cvs commit</tt> is to pass it specific 179: file names. (Usually you should do this.) 180: 181: <tt> 182: cvs commit FILENAME 183: </tt> 184: 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 188: descriptive and informative. For example: 189: 190: <ul> 191: <li>BAD - "saving my work"</li> 192: <li>GOOD - "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> 198: <tt> 199: cvs add FILENAME 200: </tt> 201: 202: Then you can run <tt>cvs commit FILENAME</tt> and this file will 203: become an "official" part of LON-CAPA. 204: 205: </li> 206: <li><a name="cvsadddir" /> 207: <h3>Using CVS: Adding directories (cvs add/import)</h3> 208: <tt> 209: cvs add DIRECTORYNAME 210: </tt> 211: 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: 216: 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: 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: 226: Once in a while, multiple programmers may be working on the 227: same file. Most conflicts are avoidable if everybody regularly 228: commits their changes AND if everybody 229: regularly updates the CVS source tree they are working on. 230: 231: 232: If you are absent from programming for a few days, and 233: fail 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: 237: </li> 238: </ul></li> 239: <li><a name="makeHTML" /> 240: <h2>Viewing the software (make HTML)</h2> 241: 242: Commands 243: 244: <tt> 245: cd loncom/build 246: rm -Rf HTML (or alternatively, "make clean") 247: make HTML 248: cd HTML 249: (look at the index.html file with a web browser such as Netscape) 250: </tt> 251: 252: General description of what happens 253: 254: 255: This is the actual make target code. 256: 257: <pre> 258:  259: HTML: 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 265:  266: </pre> 267: 268: What basically happens is that specially marked-up data in the LON-CAPA 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, 272: links, ownerships, permissions, and brief documentation of what each 273: file does. 274: 275: </li> 276: <li><a name="makebuild" /> 277: <h2>Compiling the software (make build)</h2> 278: Commands 279: <tt> 280: cd loncom/build 281: make build 282: </tt> 283: 284: General description of what happens 285: 286: 287: This is the actual make target code. 288: 289: <pre> 290:  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 300:  301: </pre> 302: 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. 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). 309: 310: 311: Example 312: 313: 314: Here is information for one file <tt>tth.so</tt> provided in 315: <tt>doc/loncapafiles/loncapafiles.lpml</tt>. 316: 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> 339: 340: <tt>loncom/build/lpml_parse.pl</tt> sees the build tags and sets up 341: a dynamic file <tt>Makefile.build</tt> to run the command inside the 342: build tags. The files listed inside the dependencies 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: 346: 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>). 349: 350: <pre> 351: all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so 352: 353: ../homework/caparesponse/capa.so: ../homework/caparesponse/caparesponse.c ../homework/caparesponse/caparesponse.pm alwaysrun 354: cd ../homework/caparesponse/; sh ./commands 355: 356: ../modules/TexConvert/tthperl/tth.so: ../modules/TexConvert/tthperl/../tthdynamic/tthfunc.c ../modules/TexConvert/tthperl/../ttmdynamic/ttmfunc.c 357: cd ../modules/TexConvert/tthperl/; sh ./commands 358: 359: alwaysrun: 360: </pre> 361: </li><li><a name="loncapafiles" /> 362: <h2>Adding/removing files from the LON-CAPA installation 363: (doc/loncapafiles/loncapafiles.html)</h2> 364: 365: To add and remove (and alter) 366: 367: 368: All that you have to do to alter the behavior of the installation is 369: edit a single file (<tt>doc/loncapafiles/loncapafiles.lpml</tt>). 370: Adding, removing, and altering files requires proper attention 371: to the syntax of file format of course. 372: 373: 374: File Format 375: 376: 377: The preceding <a href="#makebuild">"make build"</a> documentation 378: gives an example of a file 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> 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. 384: 385: 386: Philosophy and notes (the thing nobody reads) 387: 388: 389: Packaging the software from CVS onto a machine file system requires many 390: things: 391: 392: <ul> 393: <li>documenting every component of the software,</li> 394: <li>handling CVS source to file system target 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> 400: <li>providing for multiple options of installation targets (e.g. RedHat versus 401: Debian),</li> 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, 413: without having to learn any specifics (or hidden traps) of complicated 414: Makefile's or a new macro language (m4?).</li> 415: </ul> 416: 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 421: whereas we are more concerned with installation parameters). The other 422: alternative, recursive make, 423: has significant deficiencies since not all the information 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 428: <a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html"> 429: "Recursive Make Considered Harmful" by Peter Miller</a>. Other complications 430: were that, at the time, it was unclear as to what categories 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 434: as opposed to a per-directory basis. 435: Additionally, a standard big Makefile assumes certain "normalcy" to 436: the directory structure of different potential operating system directories 437: (RedHat vs. Debian). 438: 439: 440: If you take time to look at <tt>loncapafiles.lpml</tt> 441: (and perhaps run the <a href="#makeHTML">make HTML</a> command) 442: you will find that the organizing information according to the markup 443: syntax in <tt>loncapafiles.lpml</tt> is simple. Simple is good. 444: 445: 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> 449: is capable of reading and returning different types of information 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 452: of error, and has been tested in quite a number of ways. As with 453: any parser however, I remain paranoid. 454: 455: 456: Finally, some notes on the development. 457: <tt>lpml_parse.pl</tt> is very fast and styled after a state-based SAX-like 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. 466: 467: 468: The <tt>lpml_parse.pl</tt>-<tt>loncapafiles.lpml</tt> 469: combination has been highly efficient and error-free. 470: 471: </li> 472: <li><a name="makeaboutVERSION" /> 473: <h2>Updating files containing version number on your machine (make aboutVERSION)</h2> 474: Commands 475: <tt> 476: cd loncom/build 477: make aboutVERSION 478: </tt> 479: 480: General description of what happens 481: 482: 483: This is the actual make target code. 484: 485: <pre> 486:  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:  499: </pre> 500: 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: 507: 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: 510: 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: 512: </li> 513: <li><a name="configversusnonconfig" /> 514: <h2>Configurable files versus non-configurable files</h2> 515: 516: Machine-specific information is the difference 517: 518: 519: The current list of configurable files for the LON-CAPA system is 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>. 528: 529: 530: All of these configurable files contain machine-specific information. 531: For instance, the overall LON-CAPA system relies on unique host IDs such 532: as msua3, s1, s2, msul1, and 103a1 (specified as a "PerlSetVar lonHostID" 533: field within <tt>/etc/httpd/conf/loncapa.conf</tt>). 534: Non-configurable files simply do NOT have machine-specific information. 535: 536: 537: The impact on updating software 538: 539: 540: What this means in terms of software updating is that: 541: 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 546: overwritten: 547: <ol> 548: <li>have their machine-specific information saved,</li> 549: <li>be overwritten, and then</li> 550: <li>have their machine-specific information restored.</li> 551: </ol> 552: </li> 553: </ul> 554: </li> 555: <li><a name="makeinstall" /> 556: <h2>Updating the non-configurable files on your machine (make install)</h2> 557: Commands 558: <tt> 559: cd loncom/build 560: make install 561: </tt> 562: 563: General description of what happens 564: 565: 566: This is the actual make target code. 567: 568: <pre> 569:  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 586:  587: </pre> 588: 589: For safety reasons (so as to preserve a machine's configuration), 590: configuration files are NOT installed during this step. This means 591: that files such as <tt>/etc/httpd/conf/loncapa.conf</tt>, 592: <tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>, and 593: <tt>/home/httpd/spare.tab</tt> are not overwritten, but remain as old, 594: non-updated copies. (To automatically update these files and save/restore 595: their encoded machine configuration, you must run "make configinstall"). 596: 597: </li> 598: <li><a name="makeconfiginstall" /> 599: <h2>Updating the configurable files on your machine (make configinstall)</h2> 600: Commands 601: <tt> 602: cd loncom/build 603: make configinstall 604: </tt> 605: 606: General description of what happens 607: 608: 609: This is the actual make target code. 610: 611: <pre> 612:  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 623:  624: </pre> 625: 626: Configuration files are installed during this step. This means 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, 630: a backup copy is made though. Information is read out of these 631: backup copies and restored to the new files by the 632: <tt>loncaparestoreconfigurations</tt> script. To ensure that 633: new file permissions and ownerships are installed, a final set of 634: <tt>chown</tt> and <tt>chmod</tt> commands are called for each of 635: the configuration files. 636: 637: 638: For the truly paranoid 639: 640: 641: If you are truly paranoid, you can just make the 642: <tt>Makefile.configinstall</tt> file and then save, copy, 643: and restore all the configuration values yourself. 644: <tt>loncaparestoreconfigurations</tt> is pretty smart though, has yet to 645: fail, and besides, when needed, backup copies are made. 646: 647: </li><li><a name="makeRPM" /> 648: <h2>Building RPMs (make RPM)</h2> 649: 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. 653: 654: 655: Commands 656: 657: <tt> 658: cd loncom/build 659: rm -Rf BinaryRoot (or alternatively, "make clean") 660: make RPM 661: (to subsequently install, you can type commands like 662: "rpm -Uvh --force LON-CAPA-base-3.1-1.i386.rpm") 663: </tt> 664: 665: Configuration files 666: 667: 668: Configuration files are automatically saved with the file suffix 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 674: ".rpmsave" files. 675: 676: 677: General description of what happens 678: 679: 680: This is the actual make target code. 681: 682: <pre> 683:  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 688: cat base_rpm_file_list.txt | perl make_rpm.pl base 3.2 1 '' '' \ 689: BinaryRoot base_customizerpm.xml 690: 691: BinaryRoot: base_rpm_file_list 692: make TARGET='BinaryRoot' NORESTORECONF='1' install 693: 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 698:  699: </pre> 700: 701: A <tt>BinaryRoot</tt> directory is generated that reflects the locations, 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. 705: 706: 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 709: span of months) and, unlike other automated RPM-builders, cleanly 710: builds new RPMs without any after-effect of temporary files left 711: on the system. The generated RPM is labeled in the format 712: LON-CAPA-base-(VERSION)-(RELEASE).i386. VERSION is specified inside the 713: Makefile. 714: 715: </li> 716: </ol> 717: </body> 718: </html> 719: 720: 721: