--- loncom/build/readme.html 2001/01/17 11:57:59 1.8 +++ loncom/build/readme.html 2001/01/17 12:49:33 1.11 @@ -1,3 +1,9 @@ + + + +LON-CAPA Software Developer Instructions + +

LON-CAPA Software Developer Instructions

    @@ -77,10 +83,7 @@ file does.
     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)
    +make build
     
    General description of what happens @@ -96,7 +99,7 @@ build: loncom/build/parse.pl reads in all the build information out -of doc/loncapafiles/loncapafiles.html. A new Makefile named +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 @@ -106,7 +109,7 @@ all the software targets from source. T

    Here is information for one file tth.so provided in doc/loncapafiles/loncapafiles.html. - +

     
    <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"> @@ -129,8 +132,8 @@ besides documentation).

    Here is an example of a dynamically generated Makefile.build -that builds two LON-CAPA files (one of which is tth.so. - +that builds two LON-CAPA files (one of which is tth.so). +

     all: ../homework/caparesponse/capa.so ../modules/TexConvert/tthperl/tth.so 
     
    @@ -148,6 +151,101 @@ alwaysrun:
     

  1. Adding/removing files from the LON-CAPA installation (doc/loncapafiles/loncapafiles.html)

    +To add and remove (and alter) +All that you have to do to alter the behavior of the installation is +edit a single file (doc/loncapafiles/loncapafiles.html). +Adding, removing, and altering files requires proper attention +to the syntax of file format of course. +File Format +

    +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: +

      +
    • documenting every component of the software, +
    • handling CVS source to file system target information +
    • handling (according to a hierarchical scheme of grouping) file +ownership and permissions, +
    • handling (according to a hierarchical scheme of grouping) directory +ownership and permissions, +
    • handling symbolic links +
    • providing for multiple options of installation targets +(RedHat versus Debian for instance), +
    • providing for different file ownerships and permissions to apply +to the same file, +
    • allowing system software documentation to be automatically generated +(see information on "make html"), +
    • providing information in an easily adjustable form as new demands +are made on the software packaging system, +
    • providing software package information (for RPM), +
    • having information in a format that allows for troubleshooting +the current status of the machine file system, +
    • allow for changes to the structure of the CVS repository, +
    • 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?). +
    +

    +

    +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. +

  2. Configurable files versus non-configurable files

  3. @@ -157,3 +255,5 @@ alwaysrun:
  4. Building RPMs (make RPM)

+ +