File:  [LON-CAPA] / loncom / build / readme.html
Revision 1.17: download - view: text, annotated - select for diffs
Sat Apr 27 16:23:40 2002 UTC (22 years, 1 month ago) by harris41
Branches: MAIN
CVS tags: HEAD
up to date

    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: readme.html,v 1.17 2002/04/27 16:23:40 harris41 Exp $ -->
    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>
   40: 
   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 "&lt;&lt;&lt;&lt;&lt;&lt;" 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>
  242: cd loncom/build
  243: rm -Rf HTML <I>(or alternatively, "make clean")</I>
  244: make HTML
  245: cd HTML
  246: <I>(look at the index.html file with a web browser such as Netscape)</I>
  247: </pre>
  248: </font>
  249: <strong>General description of what happens</strong>
  250: <p>
  251: This is the actual make target code.
  252: <font color="#880000">
  253: <pre>
  254: <!-- LONCAPA MAKETARGET=HTML START -->
  255: HTML:
  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
  261: <!-- LONCAPA MAKETARGET=HTML END -->
  262: </pre>
  263: </font>
  264: What basically happens is that specially marked-up data in the LON-CAPA
  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
  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.
  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>
  276: cd loncom/build
  277: make build
  278: </pre>
  279: </font>
  280: <p>
  281: <strong>General description of what happens</strong>
  282: </p>
  283: <p>
  284: This is the actual make target code.
  285: <font color="#880000">
  286: <pre>
  287: <!-- LONCAPA MAKETARGET=build START -->
  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
  297: <!-- LONCAPA MAKETARGET=build END -->
  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.
  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).
  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: &lt;file&gt;
  314: &lt;source&gt;loncom/homework/caparesponse/capa.so&lt;/source&gt;
  315: &lt;target dist='default'&gt;usr/lib/perl5/site_perl/5.005/capa.so&lt;/target&gt;
  316: &lt;target dist='redhat7 redhat7.1'&gt;usr/lib/perl5/site_perl/5.6.0/capa.so&lt;/target&gt;
  317: &lt;categoryname&gt;system file&lt;/categoryname&gt;
  318: &lt;description&gt;
  319: shared library file for dynamic loading and unloading
  320: &lt;/description&gt;
  321: &lt;build trigger='always run'&gt;
  322: loncom/homework/caparesponse/commands
  323: &lt;/build&gt;
  324: &lt;dependencies&gt;
  325: caparesponse.c;
  326: caparesponse.pm;
  327: README;
  328: Makefile.PL;
  329: capa.i;
  330: commands
  331: &lt;/dependencies&gt;
  332: &lt;/file&gt;
  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>
  346: all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so 
  347: 
  348: ../homework/caparesponse/capa.so:  ../homework/caparesponse/caparesponse.c ../homework/caparesponse/caparesponse.pm alwaysrun
  349:         cd ../homework/caparesponse/; sh ./commands
  350: 
  351: ../modules/TexConvert/tthperl/tth.so:  ../modules/TexConvert/tthperl/../tthdynamic/tthfunc.c ../modules/TexConvert/tthperl/../ttmdynamic/ttmfunc.c
  352:         cd ../modules/TexConvert/tthperl/; sh ./commands
  353: 
  354: alwaysrun:
  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>
  362: All that you have to do to alter the behavior of the installation is
  363: edit a single file (<tt>doc/loncapafiles/loncapafiles.lpml</tt>).
  364: Adding, removing, and altering files requires proper attention
  365: to the syntax of file format of course.
  366: </p>
  367: <strong>File Format</strong>
  368: <P>
  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>
  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.
  376: </p>
  377: <strong>Philosophy and notes (the thing nobody reads)</strong>
  378: <p>
  379: Packaging the software from CVS onto a machine file system requires many
  380: things:
  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,
  402: without having to learn specifics (or hidden traps) of complicated Makefile's
  403: or a new macro language (m4?).</li>
  404: </ul>
  405: </p>
  406: <p>
  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
  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
  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
  424: implementation of a standard big Makefile in <tt>loncom/Makefile</tt>).
  425: Additionally, a standard big Makefile assumes certain "normalcy" to
  426: the directory structure of different potential operating system directories
  427: (RedHat vs. Debian).
  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)
  432: you will find that the organizing information according to the markup
  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>
  439: is capable of reading and returning different types of information
  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
  442: of error, and has been tested in quite a number of ways.  As with
  443: any parser however, I remain paranoid.
  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> 
  454: combination has been working very efficiently and error-free.
  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>
  462: The current list of configurable files for the LON-CAPA system is
  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.
  469: </p>
  470: <p>
  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.
  476: <strong>The impact on updating software</strong>
  477: <p>
  478: What this means in terms of software updating is that
  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>
  496: cd loncom/build
  497: make install
  498: </pre>
  499: </font>
  500: <p>
  501: <strong>General description of what happens</strong>
  502: </p>
  503: <p>
  504: This is the actual make target code.
  505: <font color="#880000">
  506: <pre>
  507: <!-- LONCAPA MAKETARGET=install START -->
  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
  524: <!-- LONCAPA MAKETARGET=install END -->
  525: </pre>
  526: </font>
  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").
  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>
  540: cd loncom/build
  541: make configinstall
  542: </pre>
  543: </font>
  544: <strong>General description of what happens</strong>
  545: <p>
  546: This is the actual make target code.
  547: <font color="#880000">
  548: <pre>
  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 -->
  557: </pre>
  558: </font>
  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
  565: <tt>loncaparestoreconfigurations</tt> script.  To ensure that
  566: new file permissions and ownerships are installed, a final set of
  567: <tt>chown</tt> and <tt>chmod</tt> commands are called for each of 
  568: the configuration files.
  569: </p>
  570: <p>
  571: <strong>For the truly paranoid</strong>
  572: </p>
  573: <p>
  574: If you are truly paranoid, you can just make the
  575: <tt>Makefile.configinstall</tt> file and then save, copy,
  576: and restore all the configuration values yourself.
  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>
  585: cd loncom/build
  586: rm -Rf BinaryRoot <I>(or alternatively, "make clean")</I>
  587: make RPM
  588:    <I>(to subsequently install, you can type commands like
  589:        "rpm -Uvh --force LON-CAPA-base-3.1-1.i386.rpm")</I>
  590: </pre>
  591: </font>
  592: </p>
  593: <strong>WARNING!!!!!!!!!!!!!!</strong>
  594: <p>
  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).
  599: </p>
  600: <p>
  601: <strong>Configuration files</strong>
  602: </p>
  603: <p>
  604: Configuration files are automatically saved with the file suffix
  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
  607: the machine-specific configuration information by running
  608: the <tt>/usr/sbin/loncaparestoreconfigurations</tt>.  However,
  609: a <b>warning</b> is important here.  If you install an RPM twice
  610: without restoring your configuration, you will overwrite the
  611: ".rpmsave" files.
  612: </p>
  613: <p>
  614: <strong>General description of what happens</strong>
  615: </p>
  616: <p>
  617: This is the actual make target code.
  618: <font color="#880000">
  619: <pre>
  620: <!-- LONCAPA MAKETARGET=RPM START -->
  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
  630: 
  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
  635: <!-- LONCAPA MAKETARGET=RPM END -->
  636: </pre>
  637: </font>
  638: A <tt>BinaryRoot</tt> directory is generated that reflects the locations,
  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.
  642: </p>
  643: <p>
  644: <tt>loncom/build/make_rpm.pl</tt> is robust (tested over the
  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).
  652: </p>
  653: </ol>
  654: </body>
  655: </html>
  656: 
  657: 
  658: 
  659: 

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>