cd loncom/build rm -Rf HTML (or alternatively, "make clean") make HTML cd HTML (look at the index.html file with a web browser such as Netscape)General description of what happens
This is the actual make target code.
HTML:
install -d HTML
cp ../../doc/loncapafiles/*.gif HTML
perl parse.pl ../../doc/loncapafiles/loncapafiles.html HTML > HTML/index.html
What basically happens is that specially marked-up data in the LON-CAPA
cvs repository file doc/loncapafiles.html is parsed into a more
viewable format by loncom/build/parse.pl. 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.
cd loncom/build make buildGeneral description of what happens
This is the actual make target code.
build:
perl parse.pl ../../doc/loncapafiles/loncapafiles.html build > Makefile.build
make -f Makefile.build all
loncom/build/parse.pl reads in all the build information out
of doc/loncapafiles/loncapafiles.html. A new Makefile named
loncom/build/Makefile.build 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).
Here is information for one file tth.so provided in
doc/loncapafiles/loncapafiles.html.
loncom/build/parse.pl sees the BUILD tags and sets up
a dynamic file Makefile.build to run the command inside the
BUILD tags (currently, DEPENDENCIES is not used for anything
besides documentation).
<METAGROUP>
<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">
<DESCRIPTION>
shared library file for dynamic loading and unloading of TeX-to-HTML functionality
</DESCRIPTION>
<BUILD>
loncom/modules/TexConvert/tthperl/commands
</BUILD>
<DEPENDENCIES>
../tthdynamic/tthfunc.c
../ttmdynamic/ttmfunc.c
</DEPENDENCIES>
Here is an example of a dynamically generated Makefile.build
that builds two LON-CAPA files (one of which is tth.so).
all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so
../homework/caparesponse/capa.so: ../homework/caparesponse/caparesponse.c ../ho
mework/caparesponse/caparesponse.pm alwaysrun
cd ../homework/caparesponse/; sh ./commands
../modules/TexConvert/tthperl/tth.so: ../modules/TexConvert/tthperl/../tthdynam
ic/tthfunc.c ../modules/TexConvert/tthperl/../ttmdynamic/ttmfunc.c
cd ../modules/TexConvert/tthperl/; sh ./commands
alwaysrun:
The preceding "make build" documentation gives an example METAGROUP entry describing one particular file. All data within loncapafiles.html is specified according to markup tags. The format and syntax of loncapafiles.html 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.
Philosophy and notes (the thing nobody reads)Packaging the software from CVS onto a machine file system requires many things:
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 "Recursive Make Considered Harmful" by Peter Miller. 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 loncom/Makefile). Additionally, a standard big Makefile assumes certain "normalcy" to the directory structure of different potential operating system directories (RedHat vs. Debian).
If you take time to look at loncapafiles.html (and perhaps run the make HTML command) you will find that the organizing information according to the markup syntax in loncapafiles.html is simple. Simple is good.
loncom/build/parse.pl is the script (invoked automatically by the various targets in loncom/build/Makefile) that reads doc/loncapafiles/loncapafiles.html. parse.pl is capable of reading and returning different types of information from loncapafiles.html depending on how parse.pl is invoked. parse.pl 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.
My regrets with the current system is that parse.pl 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 loncom/build/Makefile. Additionally, loncapafiles.html should have a DTD and all those other good SGML-ish things (and parsing should be done with a real SGML-derived parser).
On the plus side, the parse.pl-loncapafiles.html combination has been working very efficiently and error-free.