[LON-CAPA-cvs] cvs: doc /build systemperl_howto.html

Mon, 16 Dec 2002 21:23:33 -0000

This is a MIME encoded message

--matthew1040073813
Content-Type: text/plain

matthew		Mon Dec 16 16:23:33 2002 EDT

  Added files:                 
    /doc/build	systemperl_howto.html 
  Log:
  First version.  Needs more information somewhere, I'm sure.

--matthew1040073813
Content-Type: text/plain
Content-Disposition: attachment; filename="matthew-20021216162333.txt"

Index: doc/build/systemperl_howto.html
+++ doc/build/systemperl_howto.html
<html>
<head>
<title>The LON-CAPA systemperl HOW-TO</title>
</head>
<body>

<h1>The LON-CAPA systemperl HOW-TO</h1>

The LON-CAPA systemperl rpm holds all of the perl modules required by LON-CAPA
but not a part of LON-CAPA. Additionally, other libraries have been included 
as well. 
This document describes in some detail the commands and 
processes necessary to build a systemperl rpm. 
My goal in writing this document is to never, ever have to do this again. 
The difficulty is not simply the tedium involved in determining the 
dependencies and build/install orders of the packages. 
The real chore is the severity of an error - if the systemperl rpm is not 
complete, LON-CAPA will not work properly.

Fun Fact:emacs thinks 'systemperl' is a misspelling of 'distemper'.

<ol>

<li>Find a machine to build on</li>

In the case of the 3.5 systemperl, we were still support Red Hat 6.2, so 
we needed two machines. The best situation would be to have a clean install 
of RedHat and LON-CAPA (fully updated) installed in it as well. This is easy
for RedHat 7.3 but less easy for RedHat 6.2. 
For the latter case, I used data.lite.msu.edu. This caused some problems so
you should thoroughly test your rpm by doing a few test installations on 
little-used machines - preferably access servers that are not used regularly.

<li>Set up your work environment</li>

You will need to set up directories. I used <tt>/root/systemperl/</tt> 
as my base directory on data.lite.msu.edu. I had to make the following
directories:
<pre>
mkdir /root/systemperl
mkdir /root/systemperl/modules
mkdir /root/systemperl/root
mkdir /root/systemperl/root/usr
mkdir /root/systemperl/oldrpm
mkdir /root/systemperl/oldrpm/var
mkdir /root/systemperl/oldrpm/var/lib
mkdir /root/systemperl/oldrpm/var/lib/rpm
</pre>
The <tt>rpm</tt> directory is required by rpm but it can't seem to make
the directory itself. Fun Fact: rpm --usage causes a segfault on 
RedHat 7 systems.

<li>Get the old systemperl</li>

Typically found living somewhere on Zaphod. I suggest, as root, doing

<pre>
find /home -name "*systemperl*"
</pre>

The rest of this document assumes you're working with 
<tt>LON-CAPA-systemperl-3.4-1.i386.rpm</tt> as the previous version. 
The new version will be <tt>LON-CAPA-systemperl-3.5-1.i386.rpm.</tt>

<li>Figure out what was in the old rpm contains</li>

Extract the rpm to a test directory. I suggest 
<tt>/root/systemperl/oldrpm</tt>
<pre>
rpm --install --force --noscripts --nodeps -r /root/systemperl/oldrpm LON-CAPA-systemperl-3.4-1.i386.rpm
</pre>
List all the files (ls -lR) and see what perl modules and libraries are in it.
You will probably need to get all of these modules and libraries.

To get a list of new modules you may need to get, grep the loncapa source tree
using the following simple command:
<pre>
find /home/matthew/loncapa -name "*.p[lm]" -exec grep "^use " {} \; \
 | cut -d ' ' -f 2 | perl -pe 's/([\;]|\s+$)//g; $_.="\n"' | \
 grep -v ^Apache | sort -u
</pre>

<li>Get source code for libraries you need to include</li>

You may need to include libgd or some other library in the systemperl.
Google for the library and seek out the home page of the project developing it.
You'll probably wind up with a tarball instead of an rpm. (If you can find an 
rpm for all the systems you have to support I suggest just requiring people to
install the rpm directly instead of repackaging it (which I won't talk about).)
So untar it and, if you're lucky, it will use a configure script to determine
how to compile the package. For example:
<pre>
tar zxf gd-2.0.9.tar.gz
cd gd-2.0.9
./configure --prefix /root/systemperl/root/usr/
make
make install
</pre>

If you find later that some perl modules are being compiled against this
library (such as <tt>GD.pm</tt>), you will want to be sure you have this
installed properly on the machine you're building on. I suggest:
<pre>
rm -rf gd-2.0.9
tar zxf gd-2.0.9.tar.gz
cd gd-2.0.9
./configure
make
make install
</pre>

<li>Get new versions of perl modules</li>

I used CPAN. 
<pre>
# perl -MCPAN -e shell
</pre>
By issuing 'get <modulename>' commands you can grab all the files you need.

However, where the modules end up is another story. The default storage
place for modules is <tt>/root/.cpan/sources/...</tt>. 
I have not found a reliable way to set this supposedly configurable option. 
Issue a "<tt>o conf</tt>" to see what options are available in the CPAN shell.
One method might be issuing the following commands (outside of the CPAN shell):
<pre>
cd /root/.cpan
find . -name "*.tar.gz" -exec rm {} \;
perl -MCPAN -e shell
# Do your module downloading
find . -name "*.tar.gz" -exec mv {} /root/systemperl/modules \;
</pre>
Do not simply issue the above commands without knowing what they do.

The method I used was slightly more iterative, where I copied each *.tar.gz out
as it came in.

<li>Compile the Perl Modules</li>

For each module you grabbed, you'll need to issue the following commands
to compile it:
<pre>
tar zxf &lt;modulename&gt;.tar.gz
cd &lt;modulename&gt;
perl Makefile.PL PREFIX=/root/systemperl/root
make
make test
make install
</pre>
The <tt>make test</tt> is probably not necessary in some cases. Some packages
require information from you during the <tt>perl Makefile.PL</tt> step. 
Some packages will complain that you don't have prerequisite packages 
installed.
If you have already downloaded these packages you will need to install them on
the live system you are building the package on. For example, GDGraph will not
compile without GD being installed on the machine. So you must build GD.pm 
and install it on the current machine by doing
<pre>
cd GD-&lt;version&gt;
perl Makefile.PL
make
make install
</pre>
before you attempt to compile GDGraph.pm. 
Note: There is no <tt>make test</tt> for GD.pm. 

Of course, GD depends on the library libgd.so. Thus, we need to have
installed libgd prior to all of this. There is no automatic way of 
settling these dependencies at this time.

<li>Package it together</li>

Ahh, building an rpm. Legends tell of days when you had to work long and
hard to build an rpm. These days we have Scott Harrison's <tt>make_rpm.pl</tt>
script which does the hard work for us. Since you're likely to have to
do this a lot, making a shell script might be wise:
<pre>
[root@data systemperl]# cat make_systemperl.sh 
find ./root | perl make_rpm.pl LON-CAPA-systemperl 3.5 '' '' ./root
</pre>

NOTE: A modification had to be made to make_rpm.pl in order for it to
accept a name of LON-CAPA-systemperl. By default the make_rpm.pl script does
not allow for non-alphanumeric characters in the package name. This bites.
So you'll want to bypass that test in the make_rpm.pl script.

The invocation of make_rpm.pl given above omits a lot of options.
If you need to do something special with your systemperl rpm I suggest you
read the help available on make_rpm.pl.

<li>Test installation</li>

So, you've made an rpm. You should be proud. 
You could be even prouder if you knew the thing worked. 
So find a machine to test on. I suggest either a little-used access server
or a new machine you don't intend to keep around.

Do not simply install it on the machine you built on and decide it works.
The process above only gives you the modules LON-CAPA depends on. It does
not tell you which modules those modules depend on. Only actual use will
tell you if your system is complete.

Install your rpm on the system 
<pre>
rpm --install --force LON-CAPA-systemperl-3.5.-1.rpm
</pre>
and install the new loncapa. I suggest testing the following components:
<ul>
<li>kerberos 4 authentication</li>
<li>kerberos 5 authentication</li>
<li>spreadsheet, specifically excel output of spreadsheets</li>
<li>statistics, specifically the degree of difficulty graphs</li>
<li>A randomlabel problem</li>
<li>search and search results</li>
<li>enrollment upload</li>
</ul>
If there are any problems you have likely forgotten a library or have a bad
version of the library.

</ol>
</body>
</html>

--matthew1040073813--