Diff for /loncom/build/readme.html between versions 1.17 and 1.21

version 1.17, 2002/04/27 16:23:40 version 1.21, 2002/12/18 17:57:12
Line 1 Line 1
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/html4/loose.dtd">   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <!-- The LearningOnline Network with CAPA -->  <!-- The LearningOnline Network with CAPA -->
 <!-- $Id$ -->  <!-- $Id$ -->
 <html>  <html>
 <head>  <head>
   <meta http-equiv="Content-Type" content="text/html; charset=utf-8"></meta>
 <meta name="GENERATOR"  <meta name="GENERATOR"
       content="Scott Harrison and Emacs Version 3.14159265358979" />        content="Scott Harrison and Emacs Version 3.14159265358979"></meta>
 <title>LON-CAPA Software Developer Instructions</title>  <title>LON-CAPA Software Developer Guide</title>
 </head>  </head>
 <body>  <body>
 <h1>LON-CAPA Software Developer Instructions</h1>  <h1>LON-CAPA Software Developer Guide</h1>
 <p>  <p>
 <br /><i>Written by Scott Harrison, January 17, 2001</i>  <br /><i>Written by Scott,<br />
 <br /><i>Last updated, April 27, 2002</i>  <a href="mailto:sharrison@users.sourceforge.net">
   sharrison@users.sourceforge.net</a>,<br />
   January 17, 2001</i>
   <br /><i>Last updated, August 14, 2002</i>
 </p>  </p>
 <ol>  <ol>
 <li><a href="#Using_CVS">Using CVS</a></li>  <li><a href="#Using_CVS">Using CVS</a>
 <ul>  <ul>
 <li><a href="#cvslog">Logging in and out (cvs login; cvs logout)</a></li>  <li><a href="#cvslog">Logging in and out (cvs login; cvs logout)</a></li>
 <li><a href="#cvsupdate">Updating files (cvs update -d)</a></li>  <li><a href="#cvsupdate">Updating files (cvs update -d)</a></li>
Line 24 Line 28
 <li><a href="#cvsadddir">Adding directories (cvs add/import)</a></li>  <li><a href="#cvsadddir">Adding directories (cvs add/import)</a></li>
 <li><a href="#cvsnotsure">What to do when you're not sure about your files  <li><a href="#cvsnotsure">What to do when you're not sure about your files
 (cvs update)</a></li>  (cvs update)</a></li>
 </ul>  </ul></li>
 <li><a href="#makeHTML">Viewing the software (make HTML)</a></li>  <li><a href="#makeHTML">Viewing the software (make HTML)</a></li>
 <li><a href="#makebuild">Compiling the software (make build)</a></li>  <li><a href="#makebuild">Compiling the software (make build)</a></li>
 <li><a href="#loncapafiles">Adding/removing files from the LON-CAPA  <li><a href="#loncapafiles">Adding/removing files from the LON-CAPA
Line 39  machine (make configinstall)</a></li> Line 43  machine (make configinstall)</a></li>
 </ol>  </ol>
   
 <ol>  <ol>
 <a name="Using_CVS" />  
 <li><h2>Using CVS</h2></li>  <li><a name="Using_CVS" /><h2>Using CVS</h2><br />
 These instructions assume that you are using a Linux or UNIX based  These instructions assume that you are using a Linux or UNIX based
 terminal.  terminal.
 <ul>  <ul>
 <li><a name="cvslog" />  <li><a name="cvslog" />
     <h3>Using CVS: Logging in and out (cvs login; cvs logout)</h3>      <h3>Using CVS: Logging in and out (cvs login; cvs logout)</h3>
 <p>  <p>
 To log into CVS, CVS needs to be part of your system environment.  In order to log into CVS, CVS needs to be part of your system environment.
 You can accomplish this by:  You can do this by:
   </p>
   <p>
 <font color="#008800">  <font color="#008800">
 <pre>  <tt>export CVSROOT=:pserver:USERNAME@install.lon-capa.org:/home/cvs</tt>
 export CVSROOT=:pserver:USERNAME@install.lon-capa.org:/home/cvs  
 </pre>  
 </font>  </font>
 </p>  </p>
 <p>  <p>
 To actually login, you will need to execute the following command:  To actually login, you will need to execute the following command:
   </p>
   <p>
 <font color="#008800">  <font color="#008800">
 <pre>  <tt>cvs login</tt>
 cvs login  
 </pre>  
 </font>  </font>
 You will be prompted for a password.  </p>
   <p>
   You are then prompted for a password.
 If you do not have a password, or the password is not working, you  If you do not have a password, or the password is not working, you
 should contact <a href="mailto:helen@lon-capa.org">helen@lon-capa.org</a>  should contact <a href="mailto:helen@lon-capa.org">helen@lon-capa.org</a>.
   </p>
   <p>
   The first time you use CVS, you need to CHECKOUT the repository.
   Generally speaking, you need to checkout <tt>loncapa</tt> only once
   per machine.
   To check-out the repository, use the <tt>checkout</tt> command.
   (Otherwise, just enter your CVS directory, <tt>cd loncapa</tt>.)
 </p>  </p>
 <p>  <p>
 If you have yet to check out the CVS repository, you can use the  
 <tt>checkout</tt> command.  (Otherwise, just enter your  
 CVS repository, <tt>cd loncapa</tt>.)  
 <font color="#008800">  <font color="#008800">
 <pre>  <tt>cvs checkout loncapa</tt><br />
 cvs checkout loncapa  <tt>cd loncapa</tt>
 cd loncapa  
 </pre>  
 </font>  </font>
 </p>  </p>
 <p>After you have completed your work with the CVS repository, it  <p>After completing work with the CVS repository,
 is recommended that you log out:  you can log out:
   </p>
   <p>
 <font color="#008800">  <font color="#008800">
 <pre>  <tt>cvs logout</tt>
 cvs logout  
 </pre>  
 </font>  </font>
 </p>  </p>
 </li>  </li>
Line 91  cvs logout Line 99  cvs logout
 <p>  <p>
 After entering your CVS source tree (<tt>cd loncapa</tt>),  After entering your CVS source tree (<tt>cd loncapa</tt>),
 you should frequently update the software changes that  you should frequently update the software changes that
 programmers other than yourself have made.  This is done  other people have made.  This is done with the <tt>update</tt> command.
 with the <tt>update</tt> command.  </p>
   <p>
 <font color="#008800">  <font color="#008800">
 <pre>  <tt>
 cvs update -d  cvs update -d
 </pre>  </tt>
 </font>  </font>
 </p>  </p>
 <p>  <p>
 The <tt>cvs update</tt> command will give you output  The <tt>cvs update</tt> command creates output
 as it updates your CVS source tree.  Commonly you will  as it updates your CVS source tree.  Common flags are
 see 'U' and 'P' which indicate that a file has been updated with  'U' and 'P'; they indicate that a file in your
 changes another programmer has made.  <tt>loncapa</tt> directory is now updated with
   changes made by another programmer.
   </p>
   <p>
 <font color="#880000">  <font color="#880000">
 <pre>  <tt>`U FILE'</tt></font></p>
 `U FILE'  <blockquote><font color="#880000">
      The file was brought up to date with respect to the repository.  The file was brought up to date in your <tt>loncapa</tt>.
      This is done for any file that exists in the repository but not in  <br />'U' is done for:
      your source, and for files that you haven't changed but are not  <br />* any file that exists in the repository but not in your source, and
      the most recent versions available in the repository.  <br />* files that you have not changed but are not the most recent versions
   available in the repository.
   <br />The network behavior of 'U' is that the entire new file is uploaded
   from the CVS server.
   </font></blockquote>
   <p><font color="#880000"><tt>
 `P FILE'  `P FILE'
      Like `U', but the CVS server sends a patch instead of an entire  </tt></font></p>
      file.  These two things accomplish the same thing.  <blockquote><font color="#880000">
 </pre>  Like `U', but the CVS server sends a patch instead of an entire file.
 </font>  </font></blockquote>
   <p>
   'U' and 'P' essentially accomplish the same thing, just in
   different ways.
 </p>  </p>
 <p>  <p>
 Usually, when you do not <tt>cvs commit</tt> the code changes that you  Usually, when you do not <tt>cvs commit</tt> your code changes,
 make, the <tt>update</tt> command will tell you that you have modified  the <tt>update</tt> command will tell you that you have modified
 your file with the 'M' flag.  your file with the 'M' flag.
 <font color="#880000">  </p>
 <pre>  <p><font color="#880000"><tt>
 `M FILE'  `M FILE'
      The file is modified in  your  working  directory.  This is probably  </tt></font></p>
      based on changes you made and have not yet "cvs commit"-ed.  <blockquote><font color="#880000">
 </pre>       The file is modified in your working <tt>loncapa</tt> directory.
 </font>       This is probably based on changes you made and have not yet
        "cvs commit"-ed.
   </font></blockquote>
   <p>
 Sometimes, it will occur that:  Sometimes, it will occur that:
   </p>
 <ul>  <ul>
 <li>you have modified a file and not yet committed it</li>  <li>you have modified a file and not yet committed it</li>
 <li>someone else *has* modified a file and *has* committed it</li>  <li>someone else *has* modified a file and *has* committed it</li>
 </ul>  </ul>
   <p>
 Generally speaking, this is <strong>your</strong> fault.  It is your  Generally speaking, this is <strong>your</strong> fault.  It is your
 responsibility to resolve conflicts.  <tt>cvs update</tt> informs  responsibility to resolve conflicts.  <tt>cvs update</tt> informs
 you of a conflict with the 'C' flag.  you of a conflict with the 'C' flag.
 <font color="#880000">  </p>
 <pre>  <p><font color="#880000"><tt>
 `C FILE'  `C FILE'
   </tt></font></p>
   <blockquote><font color="#880000">
      A conflict was detected while trying to merge your changes to FILE       A conflict was detected while trying to merge your changes to FILE
      with changes from the source repository.       with changes from the source repository.
 </pre>  </font></blockquote>
 </font>  <p>
 You will need to open the file and examine it; CVS will have added in  You will need to open the file and examine it; CVS will have added in
 markup tags like "&lt;&lt;&lt;&lt;&lt;&lt;" to tell you about the merging  markup tags like "&lt;&lt;&lt;&lt;&lt;&lt;" to tell you about the merging
 conflicts.  (Sometimes, CVS will intelligently merge in other changes and  conflicts.  (Sometimes, CVS will intelligently merge in other changes and
Line 159  file within the repository.  If a file d Line 185  file within the repository.  If a file d
 will first need to <tt>cvs add</tt> it as described in the following  will first need to <tt>cvs add</tt> it as described in the following
 section.  section.
 </p>  </p>
 Running the <tt>cvs commit</tt> command without passing it an argument will  Running the <tt>cvs commit</tt> command without additional arguments will
 commit all changes that you have within the current directory and  commit all of your changes within the current directory and subdirectories.
 subdirectories.  <p><font color="#008800"><tt>
 <font color="#008800">  
 <pre>  
 cvs commit  cvs commit
 </pre>  </tt></font></p>
 </font>  
 </p>  
 <p>  <p>
 A more precise approach to using <tt>cvs commit</tt> is to pass it specific  A more precise approach to using <tt>cvs commit</tt> is to pass it specific
 file names.  (Usually you should do this.)  file names.  (Usually you should do this.)
 <font color="#008800">  
 <pre>  
 cvs commit FILENAME  
 </pre>  
 </font>  
 </p>  </p>
   <p><font color="#008800"><tt>
   cvs commit FILENAME
   </tt></font></p>
 <p>  <p>
 Note that CVS typically invokes the <tt>vi</tt> editor and solicits comments  Note that CVS typically invokes the
 about your latest changes to the software.   Your comments should be  <a href="http://www.eng.hawaii.edu/Tutor/vi.html">vi</a> editor and solicits
   comments about your latest changes to the software.   Your comments should be
 both short yet uniquely descriptive.  For example:  both short yet uniquely descriptive.  For example:
   </p>
 <ul>  <ul>
 <li><strong>BAD</strong> - "made some changes and am drinking soda"</li>  <li><strong>BAD</strong> - "made some changes and am drinking soda"</li>
 <li><strong>GOOD</strong> - "implemented syntax checking of perl scripts  <li><strong>GOOD</strong> - "implemented syntax checking of perl scripts
 with -c flag"</li>  with -c flag"</li>
 </ul>  </ul>
 </p>  
 </li>  </li>
 <li><a name="cvsadd" />  <li><a name="cvsadd" />
     <h3>Using CVS: Adding files (cvs add)</h3>      <h3>Using CVS: Adding files (cvs add)</h3>
 <p>  <p><font color="#008800"><tt>
 <font color="#008800">  
 <pre>  
 cvs add FILENAME  cvs add FILENAME
 </pre>  </tt></font></p>
 </font>  
 </p>  
 <p>  <p>
 Then you can run <tt>cvs commit FILENAME</tt> and this file will  Then you can run <tt>cvs commit FILENAME</tt> and this file will
 become an "official" part of LON-CAPA.  become an "official" part of LON-CAPA.
Line 204  become an "official" part of LON-CAPA. Line 221  become an "official" part of LON-CAPA.
 </li>  </li>
 <li><a name="cvsadddir" />  <li><a name="cvsadddir" />
     <h3>Using CVS: Adding directories (cvs add/import)</h3>      <h3>Using CVS: Adding directories (cvs add/import)</h3>
 <p>  <p><font color="#008800"><tt>
 <font color="#008800">  
 <pre>  
 cvs add DIRECTORYNAME  cvs add DIRECTORYNAME
 </pre>  </tt></font></p>
 </font>  
 </p>  
 <p>  <p>
 There is no need to run <tt>cvs commit</tt>.  Directories immediately  There is no need to run <tt>cvs commit</tt>.  Directories immediately
 become part of the LON-CAPA CVS source tree by only using the <tt>cvs add</tt>  become part of the LON-CAPA CVS source tree by only using the <tt>cvs add</tt>
 command.  command.
 </p>  </p>
   <p>
   You should not ordinarily need to use the <tt>cvs import</tt> command.
   If misused, <tt>cvs import</tt> can lead to the loss of code within
   the repository.
   </p>
 </li>  </li>
 <li><a name="cvsnotsure" />  <li><a name="cvsnotsure" />
     <h3>Using CVS: What to do when you're not sure about your files      <h3>Using CVS: What to do when you're not sure about your files
         (cvs update -d)</h3>          (cvs update -d)</h3>
 <p>  <p>
 Every once in a while, multiple programmers may be working on the  Once in a while, multiple programmers may be working on the
 same file.  Most conflicts are avoidable if everybody regularly  same file.  Most conflicts are avoidable if everybody regularly
 <strong>commits</strong> their changes AND if everybody  <strong>commits</strong> their changes AND if everybody
 regularly <strong>updates</strong> the CVS source tree they are working on.  regularly <strong>updates</strong> the CVS source tree they are working on.
 </p>  </p>
 <p>  <p>
 In other words, if you are absent from programming for a few days, and  If you are absent from programming for a few days, and
 <strong>fail</strong> to run <tt>cvs update -d</tt> on your CVS source  <strong>fail</strong> to run <tt>cvs update -d</tt> on your CVS source
 repository, you have only yourself to blame if you find yourself writing  repository, you have only yourself to blame if you find yourself writing
 code in a file that is not up-to-date.  code in a file that is not up-to-date.
 </p>  </p>
 </li>  </li>
 </ul>  </ul></li>
 <li><a name="makeHTML" />  <li><a name="makeHTML" />
     <h2>Viewing the software (make HTML)</h2></li>      <h2>Viewing the software (make HTML)</h2>
   <p>
 <strong>Commands</strong>  <strong>Commands</strong>
 <font color="#008800">  </p>
 <pre>  <p><font color="#008800"><tt>
 cd loncom/build  cd loncom/build<br />
 rm -Rf HTML <I>(or alternatively, "make clean")</I>  rm -Rf HTML <i>(or alternatively, "make clean")</i><br />
 make HTML  make HTML<br />
 cd HTML  cd HTML<br />
 <I>(look at the index.html file with a web browser such as Netscape)</I>  <i>(look at the index.html file with a web browser such as Netscape)</i>
 </pre>  </tt></font></p>
 </font>  <p>
 <strong>General description of what happens</strong>  <strong>General description of what happens</strong>
   </p>
 <p>  <p>
 This is the actual make target code.  This is the actual make target code.
 <font color="#880000">  </p>
 <pre>  <pre>
 <!-- LONCAPA MAKETARGET=HTML START -->  <!-- LONCAPA MAKETARGET=HTML START -->
 HTML:  HTML:
Line 260  HTML: Line 280  HTML:
  > HTML/index.html   > HTML/index.html
 <!-- LONCAPA MAKETARGET=HTML END -->  <!-- LONCAPA MAKETARGET=HTML END -->
 </pre>  </pre>
 </font>  <p>
 What basically happens is that specially marked-up data in the LON-CAPA  What basically happens is that specially marked-up data in the LON-CAPA
 cvs repository file <tt>doc/loncapafiles.lpml</tt> is parsed into a more  cvs repository file <tt>doc/loncapafiles/loncapafiles.lpml</tt> is parsed
 viewable format by <tt>loncom/build/lpml_parse.pl</tt>.  The resulting  into a more viewable format by <tt>loncom/build/lpml_parse.pl</tt>.  The
 file gives a very well organized view of all the files, directories,  resulting file gives a very well organized view of all the files, directories,
 links, ownerships, permissions, and brief documentation of what each  links, ownerships, permissions, and brief documentation of what each
 file does.  file does.
 </p>  </p>
   </li>
 <li><a name="makebuild" />  <li><a name="makebuild" />
     <h2>Compiling the software (make build)</h2>      <h2>Compiling the software (make build)</h2>
 <strong>Commands</strong>  <strong>Commands</strong>
 <font color="#008800">  <p><font color="#008800"><tt>
 <pre>  
 cd loncom/build  cd loncom/build
 make build  <br />make build
 </pre>  </tt></font></p>
 </font>  
 <p>  <p>
 <strong>General description of what happens</strong>  <strong>General description of what happens</strong>
 </p>  </p>
 <p>  <p>
 This is the actual make target code.  This is the actual make target code.
 <font color="#880000">  </p>
 <pre>  <pre>
 <!-- LONCAPA MAKETARGET=build START -->  <!-- LONCAPA MAKETARGET=build START -->
 build: Makefile.build pod2html.sh pod2man.sh  build: Makefile.build pod2html.sh pod2man.sh
Line 296  Makefile.build: $(SOURCE)/doc/loncapafil Line 315  Makefile.build: $(SOURCE)/doc/loncapafil
  > Makefile.build   > Makefile.build
 <!-- LONCAPA MAKETARGET=build END -->  <!-- LONCAPA MAKETARGET=build END -->
 </pre>  </pre>
 </font>  <p>
 <tt>loncom/build/lpml_parse.pl</tt> reads in all the build information out  <tt>loncom/build/lpml_parse.pl</tt> reads in all the build information out
 of <tt>doc/loncapafiles/loncapafiles.lpml</tt>.  A new Makefile named  of <tt>doc/loncapafiles/loncapafiles.lpml</tt>.  A new Makefile named
 <tt>loncom/build/Makefile.build</tt> is dynamically constructed.  <tt>loncom/build/Makefile.build</tt> is dynamically constructed.
 This dynamically generated Makefile is then run to build/compile  This dynamically generated Makefile is then used to build and compile
 all the software targets from source.  This currently takes 10 minutes  all the software targets from source.  This can take several minutes
 (depends on the speed of the machine you compile with).  (it depends on the speed of the machine you compile with).
 </p>  </p>
   <p>
 <strong>Example</strong>  <strong>Example</strong>
   </p>
 <p>  <p>
 Here is information for one file <tt>tth.so</tt> provided in  Here is information for one file <tt>tth.so</tt> provided in
 <tt>doc/loncapafiles/loncapafiles.lpml</tt>.  <tt>doc/loncapafiles/loncapafiles.lpml</tt>.
 <font color="#330066">  </p>
 <pre>  <pre>
 &lt;file&gt;  &lt;file&gt;
 &lt;source&gt;loncom/homework/caparesponse/capa.so&lt;/source&gt;  &lt;source&gt;loncom/homework/caparesponse/capa.so&lt;/source&gt;
Line 331  commands Line 352  commands
 &lt;/dependencies&gt;  &lt;/dependencies&gt;
 &lt;/file&gt;  &lt;/file&gt;
 </pre>  </pre>
 </font>  <p>
 <tt>loncom/build/lpml_parse.pl</tt> sees the <b>build</b> tags and sets up  <tt>loncom/build/lpml_parse.pl</tt> sees the <b>build</b> tags and sets up
 a dynamic file <tt>Makefile.build</tt> to run the command inside the  a dynamic file <tt>Makefile.build</tt> to run the command inside the
 <b>build</b> tags.  The files listed inside the <b>dependencies</b> tags  <b>build</b> tags.  The files listed inside the <b>dependencies</b> tags
Line 341  or not there is a need to compile. Line 362  or not there is a need to compile.
 <p>  <p>
 Here is an example of a dynamically generated <tt>Makefile.build</tt>  Here is an example of a dynamically generated <tt>Makefile.build</tt>
 that builds two LON-CAPA files (one of which is <tt>tth.so</tt>).  that builds two LON-CAPA files (one of which is <tt>tth.so</tt>).
 <font color="#330066">  </p>
 <pre>  <pre>
 all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so   all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so 
   
Line 353  all: ../homework/caparesponse/capa.so .. Line 374  all: ../homework/caparesponse/capa.so ..
   
 alwaysrun:  alwaysrun:
 </pre>  </pre>
 </font>  
 </p>  
 </li><li><a name="loncapafiles" />  </li><li><a name="loncapafiles" />
     <h2>Adding/removing files from the LON-CAPA installation (doc/loncapafiles/loncapafiles.html)</h2>      <h2>Adding/removing files from the LON-CAPA installation
           (doc/loncapafiles/loncapafiles.html)</h2>
   <p>
 <strong>To add and remove (and alter)</strong>  <strong>To add and remove (and alter)</strong>
   </p>
 <p>  <p>
 All that you have to do to alter the behavior of the installation is  All that you have to do to alter the behavior of the installation is
 edit a single file (<tt>doc/loncapafiles/loncapafiles.lpml</tt>).  edit a single file (<tt>doc/loncapafiles/loncapafiles.lpml</tt>).
 Adding, removing, and altering files requires proper attention  Adding, removing, and altering files requires proper attention
 to the syntax of file format of course.  to the syntax of file format of course.
 </p>  </p>
   <p>
 <strong>File Format</strong>  <strong>File Format</strong>
 <P>  </p>
 The preceding <a href=#"makebuild">"make build"</a> documentation  <p>
   The preceding <a href="#makebuild">"make build"</a> documentation
 gives an example of a <b>file</b> entry describing one particular file.  gives an example of a <b>file</b> entry describing one particular file.
 All data within <tt>loncapafiles.lpml</tt> is specified according  All data within <tt>loncapafiles.lpml</tt> is specified according
 to markup tags.  The format and syntax of <tt>loncapafiles.lpml</tt>  to markup tags.  The format and syntax of <tt>loncapafiles.lpml</tt>
Line 374  is currently best described by the HTML Line 398  is currently best described by the HTML
 loncapafiles.html (as well as, by example, seeing how various  loncapafiles.html (as well as, by example, seeing how various
 information is coded).  All in all, the syntax is quite simple.  information is coded).  All in all, the syntax is quite simple.
 </p>  </p>
   <p>
 <strong>Philosophy and notes (the thing nobody reads)</strong>  <strong>Philosophy and notes (the thing nobody reads)</strong>
   </p>
 <p>  <p>
 Packaging the software from CVS onto a machine file system requires many  Packaging the software from CVS onto a machine file system requires many
 things:  things:
   </p>
 <ul>  <ul>
 <li>documenting every component of the software,</li>  <li>documenting every component of the software,</li>
 <li>handling CVS <u>source</u> to file system <u>target</u> information,</li>  <li>handling CVS <u>source</u> to file system <u>target</u> information,</li>
Line 386  ownership and permissions,</li> Line 413  ownership and permissions,</li>
 <li>handling (according to a hierarchical scheme of grouping) directory  <li>handling (according to a hierarchical scheme of grouping) directory
 ownership and permissions,</li>  ownership and permissions,</li>
 <li>handling symbolic links,</li>  <li>handling symbolic links,</li>
 <li>providing for multiple options of installation targets  <li>providing for multiple options of installation targets (e.g. RedHat versus
 (RedHat versus Debian for instance),</li>  Debian),</li>
 <li>providing for different file ownerships and permissions to apply  <li>providing for different file ownerships and permissions to apply
 to the same file,</li>  to the same file,</li>
 <li>allowing system software documentation to be automatically generated  <li>allowing system software documentation to be automatically generated
Line 399  are made on the software packaging syste Line 426  are made on the software packaging syste
 the current status of the machine file system,</li>  the current status of the machine file system,</li>
 <li>allow for changes to the structure of the CVS repository,</li>  <li>allow for changes to the structure of the CVS repository,</li>
 <li>and something that is simple enough for any one to immediately work with,  <li>and something that is simple enough for any one to immediately work with,
 without having to learn specifics (or hidden traps) of complicated Makefile's  without having to learn any specifics (or hidden traps) of complicated
 or a new macro language (m4?).</li>  Makefile's or a new macro language (m4?).</li>
 </ul>  </ul>
 </p>  
 <p>  <p>
 I looked into, and tried, different ways of accomplishing the above  I looked into, and tried, different ways of accomplishing the above
 including automake and recursive make.  The automake system seemed quite  including automake and recursive make.  The automake system seemed quite
 complicated (and needlessly so in terms of this project since, by and large,  complicated (and needlessly so in terms of this project since, by and large,
 it works to coordinate many different types of build/compilation parameters  it works to coordinate many different types of build/compilation parameters
 whereas we are more concerned with installation parameters).  Recursive make  whereas we are more concerned with installation parameters).  The other
 has significant deficiencies in the sense that not all the information  alternative, recursive make,
   has significant deficiencies since not all the information
 is kept in one place, and there are significant levels of dependency  is kept in one place, and there are significant levels of dependency
 between all the things that must be done to keep software packaging  between all the things that must be done to keep software packaging
 up to date.  A particularly convincing article I found when looking into  up to date.  A particularly convincing article I found when looking into
 much of this was  much of this was
 <a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">  <a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">
 "Recursive Make Considered Harmful" by Peter Miller</a>.  Complicating  "Recursive Make Considered Harmful" by Peter Miller</a>.  Other complications
 matters was, at the time, it was unclear as to what categories  were that, at the time, it was unclear as to what categories
 of software files we had, and whether or not the directory structure  of software files we had, and whether or not the directory structure
 of CVS would remain constant.  With an ever-developing directory structure  of CVS would remain constant.  With an ever-developing directory structure
 to CVS, I preferred to organize the information on a per-file basis  to CVS, I preferred to organize the information on a per-file basis
 as opposed to a per-directory basis (although there is a successful  as opposed to a per-directory basis.
 implementation of a standard big Makefile in <tt>loncom/Makefile</tt>).  
 Additionally, a standard big Makefile assumes certain "normalcy" to  Additionally, a standard big Makefile assumes certain "normalcy" to
 the directory structure of different potential operating system directories  the directory structure of different potential operating system directories
 (RedHat vs. Debian).  (RedHat vs. Debian).
 </p>  </p>
 <p>  <p>
 If you take time to look at loncapafiles.lpml  If you take time to look at <tt>loncapafiles.lpml</tt>
 (and perhaps run the <a href="#makeHTML">make HTML</a> command)  (and perhaps run the <a href="#makeHTML">make HTML</a> command)
 you will find that the organizing information according to the markup  you will find that the organizing information according to the markup
 syntax in <tt>loncapafiles.lpml</tt> is simple.  Simple is good.  syntax in <tt>loncapafiles.lpml</tt> is simple.  Simple is good.
Line 443  of error, and has been tested in quite a Line 469  of error, and has been tested in quite a
 any parser however, I remain paranoid.  any parser however, I remain paranoid.
 </p>  </p>
 <p>  <p>
   Finally, some notes on the development.
 <tt>lpml_parse.pl</tt> is very fast and styled after a state-based SAX-like  <tt>lpml_parse.pl</tt> is very fast and styled after a state-based SAX-like
 approach.  Additionally, <tt>loncapafiles.lpml</tt> has a   approach.  I do eventually want to use a real XML/XSLT approach, however
 DTD (loncom/build/lpml.dtd) against which it is valid.  I hesitate to make everyone everywhere install something like
 I would like to use more ENTITY's inside <tt>lpml.dtd</tt> but currently  <a href="http://search.cpan.org/search?dist=XML-Xalan">XML::Xalan</a>.
 Perl XML modules available at CPAN do not digest complex ENTITY's that well.  Also note that <tt>loncapafiles.lpml</tt> has a 
   DTD (<tt>loncom/build/lpml.dtd</tt>) against which it is valid.
   I would also like to use more ENTITY's inside <tt>lpml.dtd</tt> but currently
   the perl XML modules available at CPAN do not digest complex ENTITY's that
   well.
 </p>  </p>
 <p>  <p>
 The <tt>lpml_parse.pl</tt>-<tt>loncapafiles.lpml</tt>   The <tt>lpml_parse.pl</tt>-<tt>loncapafiles.lpml</tt> 
 combination has been working very efficiently and error-free.  combination has been highly efficient and error-free.
 </p>  </p>
 </li><li><a name="configversusnonconfig" />  </li><li><a name="configversusnonconfig" />
     <h2>Configurable files versus non-configurable files</h2>      <h2>Configurable files versus non-configurable files</h2>
Line 460  combination has been working very effici Line 491  combination has been working very effici
 </p>  </p>
 <p>  <p>
 The current list of configurable files for the LON-CAPA system is  The current list of configurable files for the LON-CAPA system is
 /etc/httpd/access.conf, /etc/smb.conf, /etc/ntp.conf, /etc/krb.conf,  <tt>/etc/httpd/conf/loncapa.conf</tt>,
 /etc/atalk/config, /etc/ntp/step-tickers,   <tt>/etc/ntp.conf</tt>,
 /home/httpd/html/res/adm/includes/copyright.tab,   <tt>/etc/krb.conf</tt>,
 /home/httpd/html/res/adm/includes/un_keyword.tab,   <tt>/etc/ntp/step-tickers</tt>,
 /home/httpd/hosts.tab, and  <tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>,
 /home/httpd/spare.tab.  <tt>/home/httpd/html/res/adm/includes/un_keyword.tab</tt>,
   <tt>/home/httpd/hosts.tab</tt>, and
   <tt>/home/httpd/spare.tab</tt>.
 </p>  </p>
 <p>  <p>
 All of these configurable files contain machine-specific information.  All of these configurable files contain machine-specific information.
 For instance, the LON-CAPA system relies on unique host IDs such  For instance, the overall LON-CAPA system relies on unique host IDs such
 as msua3, s1, s2, msul1, and 103a1 (specified as a "PerlSetVar lonHostID"  as msua3, s1, s2, msul1, and 103a1 (specified as a "PerlSetVar lonHostID"
 field within /etc/httpd/access.conf).  field within <tt>/etc/httpd/conf/loncapa.conf</tt>).
 Non-configurable files simply do NOT have machine-specific information.  Non-configurable files simply do NOT have machine-specific information.
   </p>
   <p>
 <strong>The impact on updating software</strong>  <strong>The impact on updating software</strong>
   </p>
 <p>  <p>
 What this means in terms of software updating is that  What this means in terms of software updating is that:
   </p>
 <ul>  <ul>
 <li>non-configurable files can be simply overwritten with newer versions  <li>non-configurable files can be simply overwritten with newer versions
 (without "anything" else to worry about),</li>  (without "anything" else to worry about),</li>
 <li>and configurable files must follow these steps to be safely  <li>and configurable files must follow these steps to be safely
 overwritten</li>  overwritten:
 <ol>  <ol>
 <li>have their machine specific information saved,</li>  <li>have their machine-specific information saved,</li>
 <li>be overwritten, and then</li>  <li>be overwritten, and then</li>
 <li>have their machine specific information restored.</li>  <li>have their machine-specific information restored.</li>
 </ol>  </ol>
   </li>
 </ul>  </ul>
 </p>  </li>
 <li><a name="makeinstall" />  <li><a name="makeinstall" />
     <h2>Updating the non-configurable files on your machine (make install)</h2>      <h2>Updating the non-configurable files on your machine (make install)</h2>
 <strong>Commands</strong>  <strong>Commands</strong>
 <font color="#008800">  <p><font color="#008800"><tt>
 <pre>  
 cd loncom/build  cd loncom/build
 make install  <br />make install
 </pre>  </tt></font></p>
 </font>  
 <p>  <p>
 <strong>General description of what happens</strong>  <strong>General description of what happens</strong>
 </p>  </p>
 <p>  <p>
 This is the actual make target code.  This is the actual make target code.
 <font color="#880000">  </p>
 <pre>  <pre>
 <!-- LONCAPA MAKETARGET=install START -->  <!-- LONCAPA MAKETARGET=install START -->
 install: TEST_hosts_tab Makefile.install Makefile  install: TEST_hosts_tab Makefile.install Makefile
Line 523  Makefile.install: $(SOURCE)/doc/loncapaf Line 559  Makefile.install: $(SOURCE)/doc/loncapaf
  "$(TARGET)" > Makefile.install   "$(TARGET)" > Makefile.install
 <!-- LONCAPA MAKETARGET=install END -->  <!-- LONCAPA MAKETARGET=install END -->
 </pre>  </pre>
 </font>  <p>
 For safety reasons (so as to not mess up a machine's configuration),  For safety reasons (so as to preserve a machine's configuration),
 configuration files are NOT installed during this step.  This means  configuration files are NOT installed during this step.  This means
 that files such as /etc/httpd/access.conf, /etc/smb.conf, /etc/atalk/config,  that files such as <tt>/etc/httpd/conf/loncapa.conf</tt>,
 /home/httpd/html/res/adm/includes/copyright.tab, and  <tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>, and
 /home/httpd/spare.tab are not overwritten, but remain as old, non-updated  <tt>/home/httpd/spare.tab</tt> are not overwritten, but remain as old,
 copies.  (To automatically update these files and save/restore  non-updated copies.  (To automatically update these files and save/restore
 their encoded machine configuration, you must run "make configinstall").  their encoded machine configuration, you must run "make configinstall").
 </p>  </p>
   </li>
 <li><a name="makeconfiginstall" />  <li><a name="makeconfiginstall" />
   <h2>Updating the configurable files on your machine (make configinstall)</h2>    <h2>Updating the configurable files on your machine (make configinstall)</h2>
 <strong>Commands</strong>  <strong>Commands</strong>
 <font color="#008800">  <p><font color="#008800"><tt>
 <pre>  
 cd loncom/build  cd loncom/build
 make configinstall  make configinstall
 </pre>  </tt></font></p>
 </font>  <p>
 <strong>General description of what happens</strong>  <strong>General description of what happens</strong>
   </p>
 <p>  <p>
 This is the actual make target code.  This is the actual make target code.
 <font color="#880000">  </p>
 <pre>  <pre>
 <!-- LONCAPA MAKETARGET=configinstall START -->  <!-- LONCAPA MAKETARGET=configinstall START -->
 configinstall:   configinstall: Makefile.configinstall
         # there is a dependency on having directories in place, but oh well...   make -f Makefile.configinstall SOURCE="$(SOURCE)" TARGET="$(TARGET)" \
         perl parse.pl ../../doc/loncapafiles/loncapafiles.html configinstall > Makefile.configinstall   configfiles
         make -f Makefile.configinstall SOURCE="../.." TARGET="" configfiles   if (test "0" = $(NORESTORECONF)); then \
         perl loncaparestoreconfigurations lasttimestamp   perl loncaparestoreconfigurations suffix .lpmlnew; fi
         make -f Makefile.configinstall TARGET="" configpermissions  
   Makefile.configinstall: $(SOURCE)/doc/loncapafiles/loncapafiles.lpml lpml_parse.pl
    cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \
    perl lpml_parse.pl configinstall $(CATEGORY) $(DIST) "$(SOURCE)" \
    "$(TARGET)" > Makefile.configinstall
 <!-- LONCAPA MAKETARGET=configinstall END -->  <!-- LONCAPA MAKETARGET=configinstall END -->
 </pre>  </pre>
 </font>  <p>
 Configuration files are installed during this step.  This means  Configuration files are installed during this step.  This means
 that files such as /etc/httpd/access.conf, /etc/smb.conf, /etc/atalk/config,  that files such as <tt>/etc/httpd/conf/loncapa.conf</tt>,
 /home/httpd/html/res/adm/includes/copyright.tab, and  <tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>, and
 /home/httpd/spare.tab are overwritten.  Before being overwritten,  <tt>/home/httpd/spare.tab</tt> are overwritten.  Before being overwritten,
 a backup copy is made though.  Information is read out of these  a backup copy is made though.  Information is read out of these
 backup copies and restored to the new files by the  backup copies and restored to the new files by the
 <tt>loncaparestoreconfigurations</tt> script.  To ensure that  <tt>loncaparestoreconfigurations</tt> script.  To ensure that
Line 575  If you are truly paranoid, you can just Line 616  If you are truly paranoid, you can just
 <tt>Makefile.configinstall</tt> file and then save, copy,  <tt>Makefile.configinstall</tt> file and then save, copy,
 and restore all the configuration values yourself.  and restore all the configuration values yourself.
 <tt>loncaparestoreconfigurations</tt> is pretty smart though, has yet to  <tt>loncaparestoreconfigurations</tt> is pretty smart though, has yet to
 fail, and besides, when needed backup copies are made.  fail, and besides, when needed, backup copies are made.
 </p>  </p>
 <li><a name="makeRPM" />  </li><li><a name="makeRPM" />
     <h2>Building RPMs (make RPM)</h2>      <h2>Building RPMs (make RPM)</h2>
 <strong>Commands</strong>  <p>
 <font color="#008800">  LON-CAPA is currently installed through "intelligent tarballs".
 <pre>  What I am describing now is part of an earlier (and perhaps future) effort
 cd loncom/build  involving RPMs.
 rm -Rf BinaryRoot <I>(or alternatively, "make clean")</I>  
 make RPM  
    <I>(to subsequently install, you can type commands like  
        "rpm -Uvh --force LON-CAPA-base-3.1-1.i386.rpm")</I>  
 </pre>  
 </font>  
 </p>  </p>
 <strong>WARNING!!!!!!!!!!!!!!</strong>  
 <p>  <p>
 Never never never never never manually install the  <strong>Commands</strong>
 LON-CAPA-setup-3.1-1.i386.rpm.  This RPM is meant to only be  
 installed by the CD installation process (it wipes out  
 the existing /etc/passwd file).  
 </p>  </p>
   <p><font color="#008800"><tt>
   cd loncom/build<br />
   rm -Rf BinaryRoot <i>(or alternatively, "make clean")</i><br />
   make RPM<br />
   <i>(to subsequently install, you can type commands like
   "rpm -Uvh --force LON-CAPA-base-3.1-1.i386.rpm")</i>
   </tt></font></p>
 <p>  <p>
 <strong>Configuration files</strong>  <strong>Configuration files</strong>
 </p>  </p>
 <p>  <p>
 Configuration files are automatically saved with the file suffix  Configuration files are automatically saved with the file suffix
 ".rpmsave".  So <tt>/etc/httpd/conf/access.conf</tt> is saved as   ".rpmsave".  So <tt>/etc/httpd/conf/loncapa.conf</tt> is saved as 
 <tt>/etc/httpd/conf/access.conf.rpmsave</tt>.  You can restore  <tt>/etc/httpd/conf/loncapa.conf.rpmsave</tt>.
 the machine-specific configuration information by running  The <tt>loncaparestoreconfigurations</tt> script should work to restore
 the <tt>/usr/sbin/loncaparestoreconfigurations</tt>.  However,  configurations in this case.  However, please note that if you install an RPM
 a <b>warning</b> is important here.  If you install an RPM twice  twice without restoring your configuration, you will overwrite the
 without restoring your configuration, you will overwrite the  
 ".rpmsave" files.  ".rpmsave" files.
 </p>  </p>
 <p>  <p>
Line 615  without restoring your configuration, yo Line 652  without restoring your configuration, yo
 </p>  </p>
 <p>  <p>
 This is the actual make target code.  This is the actual make target code.
 <font color="#880000">  </p>
 <pre>  <pre>
 <!-- LONCAPA MAKETARGET=RPM START -->  <!-- LONCAPA MAKETARGET=RPM START -->
 RPM: BinaryRoot base_rpm_file_list  RPM: BinaryRoot base_rpm_file_list
  cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \   cat $(SOURCE)/doc/loncapafiles/loncapafiles.lpml | \
  perl lpml_parse.pl make_rpm $(CATEGORY) $(DIST) $(SOURCE) $(TARGET) \   perl lpml_parse.pl make_rpm $(CATEGORY) $(DIST) $(SOURCE) $(TARGET) \
  > base_customizerpm.xml   > base_customizerpm.xml
  cat base_rpm_file_list.txt | perl make_rpm.pl base 3.2 '' '' \   cat base_rpm_file_list.txt | perl make_rpm.pl base 3.2 1 '' '' \
  BinaryRoot base_customizerpm.xml   BinaryRoot base_customizerpm.xml
   
 BinaryRoot: base_rpm_file_list  BinaryRoot: base_rpm_file_list
Line 634  base_rpm_file_list: Line 671  base_rpm_file_list:
  'BinaryRoot' | sort > base_rpm_file_list.txt   'BinaryRoot' | sort > base_rpm_file_list.txt
 <!-- LONCAPA MAKETARGET=RPM END -->  <!-- LONCAPA MAKETARGET=RPM END -->
 </pre>  </pre>
 </font>  <p>
 A <tt>BinaryRoot</tt> directory is generated that reflects the locations,  A <tt>BinaryRoot</tt> directory is generated that reflects the locations,
 ownerships, permissions, and contents for all the CVS source  ownerships, permissions, and contents for all the CVS source
 files, compiled binaries, directories, and links as they should eventually  files, compiled binaries, directories, and links as they should eventually
 occur on the '/' filesystem location.  occur on the '/' filesystem location.
 </p>  </p>
 <p>  <p>
 <tt>loncom/build/make_rpm.pl</tt> is robust (tested over the  <tt>loncom/build/make_rpm.pl</tt> (also available at
   <a href="http://www.cpan.org">CPAN</a>) is robust (tested over the
 span of months) and, unlike other automated RPM-builders, cleanly  span of months) and, unlike other automated RPM-builders, cleanly
 builds new RPMs without any after-effect of temporary files left  builds new RPMs without any after-effect of temporary files left
 on the system.  (On the negative side, there are a number of  on the system.  The generated RPM is labeled in the format
 LON-CAPA specific customizations inside make_rpm.pl which, for  LON-CAPA-base-(VERSION)-(RELEASE).i386.  VERSION is specified inside the
 the sake of reusability, should eventually be removed).  Two new RPMs  Makefile.
 are generated: LON-CAPA-base-3.1-1.i386 and LON-CAPA-setup-3.1-1.i386.rpm  
 (again, never manually install LON-CAPA-setup-3.1-1.i386.rpm).  
 </p>  </p>
   </li>
 </ol>  </ol>
 </body>  </body>
 </html>  </html>
   
   
   
   

Removed from v.1.17  
changed lines
  Added in v.1.21


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