[LON-CAPA-cvs] cvs: loncom /build readme.html
harris41
lon-capa-cvs@mail.lon-capa.org
Wed, 31 Jul 2002 18:14:32 -0000
This is a MIME encoded message
--harris411028139272
Content-Type: text/plain
harris41 Wed Jul 31 14:14:32 2002 EDT
Modified files:
/loncom/build readme.html
Log:
BUG 619. FIXED.
xhtml-ified (validated against validator.w3.org); grammar greatly improved
(removing long sentences rich with
abstract qualifiers); removing references to smb.conf and atalk/config;
unfortunately I cannot colorize the pre xhtml elements like before;
removing references to the deprecated setup RPM
--harris411028139272
Content-Type: text/plain
Content-Disposition: attachment; filename="harris41-20020731141432.txt"
Index: loncom/build/readme.html
diff -u loncom/build/readme.html:1.18 loncom/build/readme.html:1.19
--- loncom/build/readme.html:1.18 Sat Apr 27 12:31:39 2002
+++ loncom/build/readme.html Wed Jul 31 14:14:31 2002
@@ -1,21 +1,25 @@
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!-- The LearningOnline Network with CAPA -->
-<!-- $Id: readme.html,v 1.18 2002/04/27 16:31:39 harris41 Exp $ -->
+<!-- $Id: readme.html,v 1.19 2002/07/31 18:14:31 harris41 Exp $ -->
<html>
<head>
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8"></meta>
<meta name="GENERATOR"
- content="Scott Harrison and Emacs Version 3.14159265358979" />
-<title>LON-CAPA Software Developer Instructions</title>
+ content="Scott Harrison and Emacs Version 3.14159265358979"></meta>
+<title>LON-CAPA Software Developer Guide</title>
</head>
<body>
-<h1>LON-CAPA Software Developer Instructions</h1>
+<h1>LON-CAPA Software Developer Guide</h1>
<p>
-<br /><i>Written by Scott Harrison, January 17, 2001</i>
-<br /><i>Last updated, April 27, 2002</i>
+<br /><i>Written by Scott,<br />
+<a href="mailto:sharrison@users.sourceforge.net">
+sharrison@users.sourceforge.net</a>,<br />
+January 17, 2001</i>
+<br /><i>Last updated, July 31, 2002</i>
</p>
<ol>
-<li><a href="#Using_CVS">Using CVS</a></li>
+<li><a href="#Using_CVS">Using CVS</a>
<ul>
<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>
@@ -24,7 +28,7 @@
<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
(cvs update)</a></li>
-</ul>
+</ul></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="#loncapafiles">Adding/removing files from the LON-CAPA
@@ -39,50 +43,54 @@
</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
terminal.
<ul>
<li><a name="cvslog" />
<h3>Using CVS: Logging in and out (cvs login; cvs logout)</h3>
<p>
-To log into CVS, CVS needs to be part of your system environment.
-You can accomplish this by:
+In order to log into CVS, CVS needs to be part of your system environment.
+You can do this by:
+</p>
+<p>
<font color="#008800">
-<pre>
-export CVSROOT=:pserver:USERNAME@install.lon-capa.org:/home/cvs
-</pre>
+<tt>export CVSROOT=:pserver:USERNAME@install.lon-capa.org:/home/cvs</tt>
</font>
</p>
<p>
To actually login, you will need to execute the following command:
+</p>
+<p>
<font color="#008800">
-<pre>
-cvs login
-</pre>
+<tt>cvs login</tt>
</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
-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>
-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">
-<pre>
-cvs checkout loncapa
-cd loncapa
-</pre>
+<tt>cvs checkout loncapa</tt><br />
+<tt>cd loncapa</tt>
</font>
</p>
-<p>After you have completed your work with the CVS repository, it
-is recommended that you log out:
+<p>After completing work with the CVS repository,
+you can log out:
+</p>
+<p>
<font color="#008800">
-<pre>
-cvs logout
-</pre>
+<tt>cvs logout</tt>
</font>
</p>
</li>
@@ -91,59 +99,77 @@
<p>
After entering your CVS source tree (<tt>cd loncapa</tt>),
you should frequently update the software changes that
-programmers other than yourself have made. This is done
-with the <tt>update</tt> command.
+other people have made. This is done with the <tt>update</tt> command.
+</p>
+<p>
<font color="#008800">
-<pre>
+<tt>
cvs update -d
-</pre>
+</tt>
</font>
</p>
<p>
-The <tt>cvs update</tt> command will give you output
-as it updates your CVS source tree. Commonly you will
-see 'U' and 'P' which indicate that a file has been updated with
-changes another programmer has made.
+The <tt>cvs update</tt> command creates output
+as it updates your CVS source tree. Common flags are
+'U' and 'P'; they indicate that a file in your
+<tt>loncapa</tt> directory is now updated with
+changes made by another programmer.
+</p>
+<p>
<font color="#880000">
-<pre>
-`U FILE'
- The file was brought up to date with respect to the repository.
- This is done for any file that exists in the repository but not in
- your source, and for files that you haven't changed but are not
- the most recent versions available in the repository.
-
+<tt>`U FILE'</tt></font></p>
+<blockquote><font color="#880000">
+The file was brought up to date in your <tt>loncapa</tt>.
+<br />'U' is done for:
+<br />* any file that exists in the repository but not in your source, and
+<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'
- Like `U', but the CVS server sends a patch instead of an entire
- file. These two things accomplish the same thing.
-</pre>
-</font>
+</tt></font></p>
+<blockquote><font color="#880000">
+Like `U', but the CVS server sends a patch instead of an entire file.
+</font></blockquote>
+<p>
+'U' and 'P' essentially accomplish the same thing, just in
+different ways.
</p>
<p>
-Usually, when you do not <tt>cvs commit</tt> the code changes that you
-make, the <tt>update</tt> command will tell you that you have modified
+Usually, when you do not <tt>cvs commit</tt> your code changes,
+the <tt>update</tt> command will tell you that you have modified
your file with the 'M' flag.
-<font color="#880000">
-<pre>
+</p>
+<p><font color="#880000"><tt>
`M FILE'
- The file is modified in your working directory. This is probably
- based on changes you made and have not yet "cvs commit"-ed.
-</pre>
-</font>
+</tt></font></p>
+<blockquote><font color="#880000">
+ The file is modified in your working <tt>loncapa</tt> directory.
+ This is probably based on changes you made and have not yet
+ "cvs commit"-ed.
+</font></blockquote>
+<p>
Sometimes, it will occur that:
+</p>
<ul>
<li>you have modified a file and not yet committed it</li>
<li>someone else *has* modified a file and *has* committed it</li>
</ul>
+<p>
Generally speaking, this is <strong>your</strong> fault. It is your
responsibility to resolve conflicts. <tt>cvs update</tt> informs
you of a conflict with the 'C' flag.
-<font color="#880000">
-<pre>
+</p>
+<p><font color="#880000"><tt>
`C FILE'
+</tt></font></p>
+<blockquote><font color="#880000">
A conflict was detected while trying to merge your changes to FILE
with changes from the source repository.
-</pre>
-</font>
+</font></blockquote>
+<p>
You will need to open the file and examine it; CVS will have added in
markup tags like "<<<<<<" to tell you about the merging
conflicts. (Sometimes, CVS will intelligently merge in other changes and
@@ -159,44 +185,35 @@
will first need to <tt>cvs add</tt> it as described in the following
section.
</p>
-Running the <tt>cvs commit</tt> command without passing it an argument will
-commit all changes that you have within the current directory and
-subdirectories.
-<font color="#008800">
-<pre>
+Running the <tt>cvs commit</tt> command without additional arguments will
+commit all of your changes within the current directory and subdirectories.
+<p><font color="#008800"><tt>
cvs commit
-</pre>
-</font>
-</p>
+</tt></font></p>
<p>
A more precise approach to using <tt>cvs commit</tt> is to pass it specific
file names. (Usually you should do this.)
-<font color="#008800">
-<pre>
-cvs commit FILENAME
-</pre>
-</font>
</p>
+<p><font color="#008800"><tt>
+cvs commit FILENAME
+</tt></font></p>
<p>
-Note that CVS typically invokes the <tt>vi</tt> editor and solicits comments
-about your latest changes to the software. Your comments should be
+Note that CVS typically invokes the
+<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:
+</p>
<ul>
<li><strong>BAD</strong> - "made some changes and am drinking soda"</li>
<li><strong>GOOD</strong> - "implemented syntax checking of perl scripts
with -c flag"</li>
</ul>
-</p>
</li>
<li><a name="cvsadd" />
<h3>Using CVS: Adding files (cvs add)</h3>
-<p>
-<font color="#008800">
-<pre>
+<p><font color="#008800"><tt>
cvs add FILENAME
-</pre>
-</font>
-</p>
+</tt></font></p>
<p>
Then you can run <tt>cvs commit FILENAME</tt> and this file will
become an "official" part of LON-CAPA.
@@ -204,52 +221,55 @@
</li>
<li><a name="cvsadddir" />
<h3>Using CVS: Adding directories (cvs add/import)</h3>
-<p>
-<font color="#008800">
-<pre>
+<p><font color="#008800"><tt>
cvs add DIRECTORYNAME
-</pre>
-</font>
-</p>
+</tt></font></p>
<p>
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>
command.
</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><a name="cvsnotsure" />
<h3>Using CVS: What to do when you're not sure about your files
(cvs update -d)</h3>
<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
<strong>commits</strong> their changes AND if everybody
regularly <strong>updates</strong> the CVS source tree they are working on.
</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
repository, you have only yourself to blame if you find yourself writing
code in a file that is not up-to-date.
</p>
</li>
-</ul>
+</ul></li>
<li><a name="makeHTML" />
- <h2>Viewing the software (make HTML)</h2></li>
+ <h2>Viewing the software (make HTML)</h2>
+<p>
<strong>Commands</strong>
-<font color="#008800">
-<pre>
-cd loncom/build
-rm -Rf HTML <I>(or alternatively, "make clean")</I>
-make HTML
-cd HTML
-<I>(look at the index.html file with a web browser such as Netscape)</I>
-</pre>
-</font>
+</p>
+<p><font color="#008800"><tt>
+cd loncom/build<br />
+rm -Rf HTML <i>(or alternatively, "make clean")</i><br />
+make HTML<br />
+cd HTML<br />
+<i>(look at the index.html file with a web browser such as Netscape)</i>
+</tt></font></p>
+<p>
<strong>General description of what happens</strong>
+</p>
<p>
This is the actual make target code.
-<font color="#880000">
+</p>
<pre>
<!-- LONCAPA MAKETARGET=HTML START -->
HTML:
@@ -260,29 +280,28 @@
> HTML/index.html
<!-- LONCAPA MAKETARGET=HTML END -->
</pre>
-</font>
+<p>
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
-viewable format by <tt>loncom/build/lpml_parse.pl</tt>. The resulting
-file gives a very well organized view of all the files, directories,
+cvs repository file <tt>doc/loncapafiles/loncapafiles.lpml</tt> is parsed
+into a more viewable format by <tt>loncom/build/lpml_parse.pl</tt>. The
+resulting file gives a very well organized view of all the files, directories,
links, ownerships, permissions, and brief documentation of what each
file does.
</p>
+</li>
<li><a name="makebuild" />
<h2>Compiling the software (make build)</h2>
<strong>Commands</strong>
-<font color="#008800">
-<pre>
+<p><font color="#008800"><tt>
cd loncom/build
-make build
-</pre>
-</font>
+<br />make build
+</tt></font></p>
<p>
<strong>General description of what happens</strong>
</p>
<p>
This is the actual make target code.
-<font color="#880000">
+</p>
<pre>
<!-- LONCAPA MAKETARGET=build START -->
build: Makefile.build pod2html.sh pod2man.sh
@@ -296,19 +315,21 @@
> Makefile.build
<!-- LONCAPA MAKETARGET=build END -->
</pre>
-</font>
+<p>
<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
<tt>loncom/build/Makefile.build</tt> is dynamically constructed.
-This dynamically generated Makefile is then run to build/compile
-all the software targets from source. This currently takes 10 minutes
-(depends on the speed of the machine you compile with).
+This dynamically generated Makefile is then used to build and compile
+all the software targets from source. This can take several minutes
+(it depends on the speed of the machine you compile with).
</p>
+<p>
<strong>Example</strong>
+</p>
<p>
Here is information for one file <tt>tth.so</tt> provided in
<tt>doc/loncapafiles/loncapafiles.lpml</tt>.
-<font color="#330066">
+</p>
<pre>
<file>
<source>loncom/homework/caparesponse/capa.so</source>
@@ -331,7 +352,7 @@
</dependencies>
</file>
</pre>
-</font>
+<p>
<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
<b>build</b> tags. The files listed inside the <b>dependencies</b> tags
@@ -341,7 +362,7 @@
<p>
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>).
-<font color="#330066">
+</p>
<pre>
all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so
@@ -353,20 +374,23 @@
alwaysrun:
</pre>
-</font>
-</p>
</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>
+</p>
<p>
All that you have to do to alter the behavior of the installation is
edit a single file (<tt>doc/loncapafiles/loncapafiles.lpml</tt>).
Adding, removing, and altering files requires proper attention
to the syntax of file format of course.
</p>
+<p>
<strong>File Format</strong>
-<P>
-The preceding <a href=#"makebuild">"make build"</a> documentation
+</p>
+<p>
+The preceding <a href="#makebuild">"make build"</a> documentation
gives an example of a <b>file</b> entry describing one particular file.
All data within <tt>loncapafiles.lpml</tt> is specified according
to markup tags. The format and syntax of <tt>loncapafiles.lpml</tt>
@@ -374,10 +398,13 @@
loncapafiles.html (as well as, by example, seeing how various
information is coded). All in all, the syntax is quite simple.
</p>
+<p>
<strong>Philosophy and notes (the thing nobody reads)</strong>
+</p>
<p>
Packaging the software from CVS onto a machine file system requires many
things:
+</p>
<ul>
<li>documenting every component of the software,</li>
<li>handling CVS <u>source</u> to file system <u>target</u> information,</li>
@@ -386,8 +413,8 @@
<li>handling (according to a hierarchical scheme of grouping) directory
ownership and permissions,</li>
<li>handling symbolic links,</li>
-<li>providing for multiple options of installation targets
-(RedHat versus Debian for instance),</li>
+<li>providing for multiple options of installation targets (e.g. RedHat versus
+Debian),</li>
<li>providing for different file ownerships and permissions to apply
to the same file,</li>
<li>allowing system software documentation to be automatically generated
@@ -399,35 +426,34 @@
the current status of the machine file system,</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,
-without having to learn specifics (or hidden traps) of complicated Makefile's
-or a new macro language (m4?).</li>
+without having to learn any specifics (or hidden traps) of complicated
+Makefile's or a new macro language (m4?).</li>
</ul>
-</p>
<p>
I looked into, and tried, different ways of accomplishing the above
including automake and recursive make. The automake system seemed quite
complicated (and needlessly so in terms of this project since, by and large,
it works to coordinate many different types of build/compilation parameters
-whereas we are more concerned with installation parameters). Recursive make
-has significant deficiencies in the sense that not all the information
+whereas we are more concerned with installation parameters). The other
+alternative, recursive make,
+has significant deficiencies since not all the information
is kept in one place, and there are significant levels of dependency
between all the things that must be done to keep software packaging
up to date. A particularly convincing article I found when looking into
much of this was
<a href="http://www.pcug.org.au/~millerp/rmch/recu-make-cons-harm.html">
-"Recursive Make Considered Harmful" by Peter Miller</a>. Complicating
-matters was, at the time, it was unclear as to what categories
+"Recursive Make Considered Harmful" by Peter Miller</a>. Other complications
+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 CVS would remain constant. With an ever-developing directory structure
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
-implementation of a standard big Makefile in <tt>loncom/Makefile</tt>).
+as opposed to a per-directory basis.
Additionally, a standard big Makefile assumes certain "normalcy" to
the directory structure of different potential operating system directories
(RedHat vs. Debian).
</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)
you will find that the organizing information according to the markup
syntax in <tt>loncapafiles.lpml</tt> is simple. Simple is good.
@@ -443,15 +469,20 @@
any parser however, I remain paranoid.
</p>
<p>
+Finally, some notes on the development.
<tt>lpml_parse.pl</tt> is very fast and styled after a state-based SAX-like
-approach. Additionally, <tt>loncapafiles.lpml</tt> has a
-DTD (loncom/build/lpml.dtd) against which it is valid.
-I would like to use more ENTITY's inside <tt>lpml.dtd</tt> but currently
-Perl XML modules available at CPAN do not digest complex ENTITY's that well.
+approach. I do eventually want to use a real XML/XSLT approach, however
+I hesitate to make everyone everywhere install something like
+<a href="http://search.cpan.org/search?dist=XML-Xalan">XML::Xalan</a>.
+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>
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>
</li><li><a name="configversusnonconfig" />
<h2>Configurable files versus non-configurable files</h2>
@@ -460,49 +491,54 @@
</p>
<p>
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,
-/etc/atalk/config, /etc/ntp/step-tickers,
-/home/httpd/html/res/adm/includes/copyright.tab,
-/home/httpd/html/res/adm/includes/un_keyword.tab,
-/home/httpd/hosts.tab, and
-/home/httpd/spare.tab.
+<tt>/etc/httpd/conf/loncapa.conf</tt>,
+<tt>/etc/ntp.conf</tt>,
+<tt>/etc/krb.conf</tt>,
+<tt>/etc/ntp/step-tickers</tt>,
+<tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>,
+<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>
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"
-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.
+</p>
+<p>
<strong>The impact on updating software</strong>
+</p>
<p>
-What this means in terms of software updating is that
+What this means in terms of software updating is that:
+</p>
<ul>
<li>non-configurable files can be simply overwritten with newer versions
(without "anything" else to worry about),</li>
<li>and configurable files must follow these steps to be safely
-overwritten</li>
+overwritten:
<ol>
-<li>have their machine specific information saved,</li>
+<li>have their machine-specific information saved,</li>
<li>be overwritten, and then</li>
-<li>have their machine specific information restored.</li>
+<li>have their machine-specific information restored.</li>
</ol>
+</li>
</ul>
-</p>
+</li>
<li><a name="makeinstall" />
<h2>Updating the non-configurable files on your machine (make install)</h2>
<strong>Commands</strong>
-<font color="#008800">
-<pre>
+<p><font color="#008800"><tt>
cd loncom/build
-make install
-</pre>
-</font>
+<br />make install
+</tt></font></p>
<p>
<strong>General description of what happens</strong>
</p>
<p>
This is the actual make target code.
-<font color="#880000">
+</p>
<pre>
<!-- LONCAPA MAKETARGET=install START -->
install: TEST_hosts_tab Makefile.install Makefile
@@ -523,28 +559,29 @@
"$(TARGET)" > Makefile.install
<!-- LONCAPA MAKETARGET=install END -->
</pre>
-</font>
-For safety reasons (so as to not mess up a machine's configuration),
+<p>
+For safety reasons (so as to preserve a machine's configuration),
configuration files are NOT installed during this step. This means
-that files such as /etc/httpd/access.conf, /etc/smb.conf, /etc/atalk/config,
-/home/httpd/html/res/adm/includes/copyright.tab, and
-/home/httpd/spare.tab are not overwritten, but remain as old, non-updated
-copies. (To automatically update these files and save/restore
+that files such as <tt>/etc/httpd/conf/loncapa.conf</tt>,
+<tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>, and
+<tt>/home/httpd/spare.tab are not overwritten</tt>, but remain as old,
+non-updated copies. (To automatically update these files and save/restore
their encoded machine configuration, you must run "make configinstall").
</p>
+</li>
<li><a name="makeconfiginstall" />
<h2>Updating the configurable files on your machine (make configinstall)</h2>
<strong>Commands</strong>
-<font color="#008800">
-<pre>
+<p><font color="#008800"><tt>
cd loncom/build
make configinstall
-</pre>
-</font>
+</tt></font></p>
+<p>
<strong>General description of what happens</strong>
+</p>
<p>
This is the actual make target code.
-<font color="#880000">
+</p>
<pre>
<!-- LONCAPA MAKETARGET=configinstall START -->
configinstall: Makefile.configinstall
@@ -559,11 +596,11 @@
"$(TARGET)" > Makefile.configinstall
<!-- LONCAPA MAKETARGET=configinstall END -->
</pre>
-</font>
+<p>
Configuration files are installed during this step. This means
-that files such as /etc/httpd/access.conf, /etc/smb.conf, /etc/atalk/config,
-/home/httpd/html/res/adm/includes/copyright.tab, and
-/home/httpd/spare.tab are overwritten. Before being overwritten,
+that files such as <tt>/etc/httpd/conf/loncapa.conf</tt>,
+<tt>/home/httpd/html/res/adm/includes/copyright.tab</tt>, and
+<tt>/home/httpd/spare.tab</tt> are overwritten. Before being overwritten,
a backup copy is made though. Information is read out of these
backup copies and restored to the new files by the
<tt>loncaparestoreconfigurations</tt> script. To ensure that
@@ -579,42 +616,35 @@
<tt>Makefile.configinstall</tt> file and then save, copy,
and restore all the configuration values yourself.
<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>
</li><li><a name="makeRPM" />
<h2>Building RPMs (make RPM)</h2>
<p>
-LON-CAPA is currently installed through "intelligent tarballs". This
-is part of an earlier (and perhaps future) effort involving RPMs.
-<strong>Commands</strong>
-<font color="#008800">
-<pre>
-cd loncom/build
-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>
+LON-CAPA is currently installed through "intelligent tarballs".
+What I am describing now is part of an earlier (and perhaps future) effort
+involving RPMs.
</p>
-<strong>WARNING!!!!!!!!!!!!!!</strong>
<p>
-Never never never never never manually install the
-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).
+<strong>Commands</strong>
</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>
<strong>Configuration files</strong>
</p>
<p>
Configuration files are automatically saved with the file suffix
-".rpmsave". So <tt>/etc/httpd/conf/access.conf</tt> is saved as
-<tt>/etc/httpd/conf/access.conf.rpmsave</tt>. You can restore
-the machine-specific configuration information by running
-the <tt>/usr/sbin/loncaparestoreconfigurations</tt>. However,
-a <b>warning</b> is important here. If you install an RPM twice
-without restoring your configuration, you will overwrite the
+".rpmsave". So <tt>/etc/httpd/conf/loncapa.conf</tt> is saved as
+<tt>/etc/httpd/conf/loncapa.conf.rpmsave</tt>.
+The <tt>loncaparestoreconfigurations</tt> script should work to restore
+configurations in this case. However, please note that if you install an RPM
+twice without restoring your configuration, you will overwrite the
".rpmsave" files.
</p>
<p>
@@ -622,7 +652,7 @@
</p>
<p>
This is the actual make target code.
-<font color="#880000">
+</p>
<pre>
<!-- LONCAPA MAKETARGET=RPM START -->
RPM: BinaryRoot base_rpm_file_list
@@ -641,27 +671,25 @@
'BinaryRoot' | sort > base_rpm_file_list.txt
<!-- LONCAPA MAKETARGET=RPM END -->
</pre>
-</font>
+<p>
A <tt>BinaryRoot</tt> directory is generated that reflects the locations,
ownerships, permissions, and contents for all the CVS source
files, compiled binaries, directories, and links as they should eventually
occur on the '/' filesystem location.
</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
builds new RPMs without any after-effect of temporary files left
-on the system. (On the negative side, there are a number of
-LON-CAPA specific customizations inside make_rpm.pl which, for
-the sake of reusability, should eventually be removed). Two new RPMs
-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).
+on the system. The generated RPM is labeled in the format
+LON-CAPA-base-(VERSION)-1.i386. VERSION is specified inside the
+Makefile.
</p>
</li>
</ol>
</body>
</html>
-
--harris411028139272--