|
version 1.8, 2001/01/17 11:57:59
|
version 1.11, 2001/01/17 12:49:33
|
|
Line 1
|
Line 1
|
| |
<HTML> |
| |
<HEAD> |
| |
<META NAME="GENERATOR" CONTENT="Scott Harrison and Emacs Version 3.14159265358979"> |
| |
<TITLE>LON-CAPA Software Developer Instructions</TITLE> |
| |
</HEAD> |
| |
<BODY> |
| <H1>LON-CAPA Software Developer Instructions</H1> |
<H1>LON-CAPA Software Developer Instructions</H1> |
| |
|
| <OL> |
<OL> |
|
Line 77 file does.
|
Line 83 file does.
|
| <FONT COLOR="#008800"> |
<FONT COLOR="#008800"> |
| <PRE> |
<PRE> |
| cd loncom/build |
cd loncom/build |
| rm -Rf HTML <I>(or alternatively, "make clean")</I> |
make build |
| make HTML |
|
| cd HTML |
|
| <I>(look at the index.html file with a web browser such as Netscape)</I> |
|
| </PRE> |
</PRE> |
| </FONT> |
</FONT> |
| <STRONG>General description of what happens</STRONG> |
<STRONG>General description of what happens</STRONG> |
|
Line 96 build:
|
Line 99 build:
|
| </PRE> |
</PRE> |
| </FONT> |
</FONT> |
| <TT>loncom/build/parse.pl</TT> reads in all the build information out |
<TT>loncom/build/parse.pl</TT> reads in all the build information out |
| of <TT>doc/loncapafiles/loncapafiles.html. A new Makefile named |
of <TT>doc/loncapafiles/loncapafiles.html</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 run to build/compile |
| all the software targets from source. This currently takes 10 minutes |
all the software targets from source. This currently takes 10 minutes |
|
Line 106 all the software targets from source. T
|
Line 109 all the software targets from source. T
|
| <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.html</TT>. |
<TT>doc/loncapafiles/loncapafiles.html</TT>. |
| <FONT COLOR="#660033"> |
<FONT COLOR="#330066"> |
| <PRE> |
<PRE> |
| <BR><METAGROUP> |
<BR><METAGROUP> |
| <BR><LONCAPA TYPE=LOCATION DIST="redhat6.2" SOURCE="loncom/modules/TexConvert/tthperl/tth.so" TARGET="usr/lib/perl5/site_perl/5.005/tth.so" CATEGORY="system file"> |
<BR><LONCAPA TYPE=LOCATION DIST="redhat6.2" SOURCE="loncom/modules/TexConvert/tthperl/tth.so" TARGET="usr/lib/perl5/site_perl/5.005/tth.so" CATEGORY="system file"> |
|
Line 129 besides documentation).
|
Line 132 besides documentation).
|
| </P> |
</P> |
| <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="#660033"> |
<FONT COLOR="#330066"> |
| <PRE> |
<PRE> |
| all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so |
all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so |
| |
|
|
Line 148 alwaysrun:
|
Line 151 alwaysrun:
|
| </P> |
</P> |
| <LI><A NAME="loncapafiles"> |
<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> |
| |
<STRONG>To add and remove (and alter)</STRONG> |
| |
All that you have to do to alter the behavior of the installation is |
| |
edit a single file (<TT>doc/loncapafiles/loncapafiles.html</TT>). |
| |
Adding, removing, and altering files requires proper attention |
| |
to the syntax of file format of course. |
| |
<STRONG>File Format</STRONG> |
| |
<P> |
| |
The preceding <A HREF=#"makebuild">"make build"</A> documentation |
| |
gives an example <B>METAGROUP</B> entry describing one particular file. |
| |
All data within <TT>loncapafiles.html</TT> is specified according |
| |
to markup tags. The format and syntax of <TT>loncapafiles.html</TT> |
| |
is currently best described by the HTML documentation code at the beginning of |
| |
loncapafiles.html (as well as, by example, seeing how various |
| |
information is coded). All in all, the syntax is quite simple. |
| |
</P> |
| |
<STRONG>Philosophy and notes (the thing nobody reads)</STRONG> |
| |
<P> |
| |
Packaging the software from CVS onto a machine file system requires many |
| |
things: |
| |
<UL> |
| |
<LI>documenting every component of the software, |
| |
<LI>handling CVS <U>source</U> to file system <U>target</U> information |
| |
<LI>handling (according to a hierarchical scheme of grouping) file |
| |
ownership and permissions, |
| |
<LI>handling (according to a hierarchical scheme of grouping) directory |
| |
ownership and permissions, |
| |
<LI>handling symbolic links |
| |
<LI>providing for multiple options of installation targets |
| |
(RedHat versus Debian for instance), |
| |
<LI>providing for different file ownerships and permissions to apply |
| |
to the same file, |
| |
<LI>allowing system software documentation to be automatically generated |
| |
(see information on <A HREF="#makeHTML">"make html"</A>), |
| |
<LI>providing information in an easily adjustable form as new demands |
| |
are made on the software packaging system, |
| |
<LI>providing software package information (for RPM), |
| |
<LI>having information in a format that allows for troubleshooting |
| |
the current status of the machine file system, |
| |
<LI>allow for changes to the structure of the CVS repository, |
| |
<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?). |
| |
</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 |
| |
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 |
| |
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>). |
| |
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.html |
| |
(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.html</TT> is simple. Simple is good. |
| |
</P> |
| |
<P> |
| |
<TT>loncom/build/parse.pl</TT> is the script (invoked automatically |
| |
by the various targets in <TT>loncom/build/Makefile</TT>) that reads |
| |
<TT>doc/loncapafiles/loncapafiles.html</TT>. <TT>parse.pl</TT> |
| |
is capable of reading and returning different types of information |
| |
from <TT>loncapafiles.html</TT> depending on how <TT>parse.pl</TT> |
| |
is invoked. <TT>parse.pl</TT> has yet to have introduced new sources |
| |
of error, and has been tested in quite a number of ways. As with |
| |
any parser however, I remain paranoid. |
| |
</P> |
| |
<P> |
| |
My regrets with the current system is that <TT>parse.pl</TT> is |
| |
slow (can take 1 minute to run) and includes a few tidbits of code, |
| |
specific to the make process, that probably should be in |
| |
<TT>loncom/build/Makefile</TT>. Additionally, <TT>loncapafiles.html</TT> |
| |
should have a DTD and all those other good SGML-ish things (and parsing |
| |
should be done with a real SGML-derived parser). |
| |
</P> |
| |
<P> |
| |
On the plus side, the <TT>parse.pl</TT>-<TT>loncapafiles.html</TT> |
| |
combination has been working very efficiently and error-free. |
| |
</P> |
| <LI><A NAME="configversusnonconfig"> |
<LI><A NAME="configversusnonconfig"> |
| <H2>Configurable files versus non-configurable files</H2> |
<H2>Configurable files versus non-configurable files</H2> |
| <LI><A NAME="makeinstall"> |
<LI><A NAME="makeinstall"> |
|
Line 157 alwaysrun:
|
Line 255 alwaysrun:
|
| <LI><A NAME="makeRPM"> |
<LI><A NAME="makeRPM"> |
| <H2>Building RPMs (make RPM)</H2> |
<H2>Building RPMs (make RPM)</H2> |
| </OL> |
</OL> |
| |
</BODY> |
| |
</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