|
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 "<<<<<<" to tell you about the merging |
markup tags like "<<<<<<" 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> |
| <file> |
<file> |
| <source>loncom/homework/caparesponse/capa.so</source> |
<source>loncom/homework/caparesponse/capa.so</source> |
|
Line 331 commands
|
Line 352 commands
|
| </dependencies> |
</dependencies> |
| </file> |
</file> |
| </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> |
| |
|
| |
|
| |
|
| |
|
![[BACK]](/icons/back.gif){kind=icon}
Return to readme.html CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [LON-CAPA] / loncom / build