OKlibrary  0.2.1.6
general.hpp File Reference

Plans for the masterscript, the "user-interface" to the build system. More...

Go to the source code of this file.


Detailed Description

Plans for the masterscript, the "user-interface" to the build system.

Similar to the use of "git" in a Git-repository, we use "oklib" in an OKplatform-installation.

Todo:
Update of pulling and pushing facilities
Todo:
Markers instead of links
  • Once oklib is available, the temporary definitions of OKplatform etc. in the makefiles shall be removed.
  • The current system of deciding globally which makefile to select is too inflexible: In principle the old system (with its local signs) has its merits, only we do not need links anymore to the resp. makefiles, but each directory contains a specific marker --- initially this is just an empty file (only the name matters), but later it might be filled with additional information on targets to be compiled and on dependencies.
    1. The problems with variable srcdir can easily be solved now --- simplest is perhaps to set this variable explicitely when calling a makefile.
    2. Yet the recursive makefile doesn't enter a directory if it doesn't contain a makefile; perhaps we get rid off the different forms of recursive makefiles altogether: for directories containing a marker "recursive.mak" oklib collects all paths through such dispensers until a marker for a "real" makefile is found, and then executes all such real makefiles.
    3. A technical problem here is that we want only to consider continuous chaines of dispensers (a missing one means that this directory is blocked): Via "find" we cannot realise it, while just searching for all paths to those markers for real makefiles is trivial via "find". One could write a little recursive programs for collecting all such paths.
    4. Perhaps easiest is that oklib calls itself recursively!
    5. So then oklib only enters action (if not given a special option) if either the current directory contains "recursive.mak" in which case oklib is called recursively on its subdirectories, or if it contains "definitions.mak" in which case the makefile for ExternalSources, OKlibBuilding or Annotations is called --- perhaps this is indicated in the name.
    6. On the other hand, as discussed in "Improved makefiles" below, perhaps the most general (and sufficient) model is actually just to ignore directories with no marker, but otherwise handle all directories below.
    7. Thus, whether oklib is implemented recursively, or works with a list created by "find", is an implementation detail.
    8. The marker "recursive.mak" would not be needed --- only positive markers (indicating local targets, and indicated which makefile is responsible)!
  • The content of the old files definitions.mak shall be made superfluous, so that at this time only an empty marker is needed.
  • So by default always all directories below the calling directory are examined recursivly; by an option ("--non-recursive") this can be disabled.
Todo:
Improved makefiles
  • Five (partially new) main makefiles:
    1. Buildsystem/ExternalSources/Makefile
    2. Buildsystem/OKlibBuilding/Makefile
    3. Buildsystem/Makefile
    4. Buildsystem/Html/Makefile (takes over targets html and internet from current Buildsystem/OKlibBuilding/Makefile)
    5. Buildsystem/Latex/Makefile (the current Buildsystem/Annotations.mak)
    These should be updated according to their plans.
  • In preparation for the truly global build system (which knows about all(!) dependencies and all rules), perhaps a new master-makefile "Master.mak" includes the configuration makefile and the above main makefiles?
  • So the target-sets for the main makefiles then should be disjoint? For common targets like "all" we could introduce a scoping:
    1. "esc" for ExternalSources
    2. "htm" for Html
    3. "lat" for Latex
    4. "lib" for OKlibBuilding
    And there must be new "super"-targets like "all = htm::all + lat::all + lib::all".
  • We need access to all files produced by the makefiles, so that we have the possibilities to express dependencies like:
    1. linking dependencies within our library
    2. linking dependencies to external libraries
    3. dependencies from executables (for example for application tests)
    4. dependencies from tools
    The goal is that the build system knows about all dependencies and all rules to resolve these dependencies, and if called at a level high enough (highest at OKplatform-level, with "oklib world") updates everything in perfect order (including external sources, compilers, tools, documentation).
  • Such a dependency would typically be just a path, for example to a source-library directory, to a link-library, or to an executable; likely these paths should be full. A target like "boost" is then just translated into such full targets.
  • So for example the expanded target "boost" (in at least the two specialised forms of source- and link-library) is a prerequisite at many places, but only in ExternalSources the makefile knows how to create/update this target (better "virtual makefile" --- managed by oklib).
  • Every "place" (directory) has its own responsibilities, the targets it creates, and from what they depend (where possibly it doesn't know how to create/update the dependencies, since they belong into the responsibility of another place), and the master-makefile collects all this information from places below the calling place. Perhaps (for speed etc.) we still keep the old recursive mode alive (as an option).
  • So we have the "recursive mode" which *calls* makefiles, and the "global mode" which *includes* makefiles.
  • The current definitions.mak actually stand for created makefiles; perhaps we still maintain that level, have somewhere the created makefile available, and then for global processing we can just include all these local makefiles. In this way we could still design makefiles with only local responsibility?! The question then is how to glue them together on the overlapping targets like "all". In "global mode" these all's need to be qualified, and glued together by some super-all.
  • In a created make-file we had definitions "srcdir=..." followed by "include OKlibBuilding/Makefile", for each relevant directory; perhaps another variable qualifies the generic targets. Such a construction should be constructible by a make-loop.
  • We should experiment with this design; looks attractive, that we can get all theglobal power by just using (generalised) local makefiles (which care only about their home-directory, and not about directories below them).
  • For the inclusion-model we have to solve a similar problem as in the call-model, namely how to arrange for inhibited directories. Perhaps all what we need is that certain directories are just inactive (qualified by not having definitions.mak), while still directories below that level might be active --- the current model, where we just "block" directories (which always includes everything below) is not flexible enough.
Todo:
Further enhancements
  • It seems we should remove the "command"-construction.
    1. The point was the echo.
    2. This is applied inconsistently, and doesn't seem useful anymore.
    3. Otherwise it just causes complications.
  • And exit-values should reflect the last return-value.
  • DONE (just use "maxima_lisp_name_okl=ecl maxima_recommended_version_number_okl=5.16.3 oklib --maxima further_arguments") As we have it now, passing all arguments to Maxima, we cannot pass for example different targets to the makefile --- we somehow need a (convenient) possibility to have both possibilities.
    • As an example, we want something like
      oklib maxima_recommended_version_number_okl=5.16.3 maxima_lisp_name_okl=ecl --maxima further_arguments_for_maxima
           
      (using here Maxima for a specific version with a specific Lisp).
    • So one could search for "--maxima", and pass everything before as parameters to the make-file.
  • --help
  • Write "oklib --sage", similar to "oklib --maxima".
    1. First without anything else.
    2. Later we must add support for our Maxima-system.
  • DONE Git operations:
    1. We handle special operations where specific settings from the OKlibrary are needed.
    2. But otherwise the users should use git himself: He needs to get used to git and its documentation, and doing it ourselfes might create trouble.
  • DONE (now all output is always both shown and copied to the log-file) It seems hard to avoid, and also not important, that if we interrupt the makefile for external sources, then the error messages are not printed --- we know it anyway. Nevertheless one could ponder again about it.
  • DONE (now all output is always both shown and copied to the log-file) If oklib-building is interrupted, then nothing is shown (also not in the log-file); hard to avoid, and not really important. But perhaps in case everything went through, then a success report with date and time should be printed (totgether with the targets), so that one can see what's done.
Todo:
Add file template generation option
  • A command to generate the default files for a maxima file, C++ file etc would be very useful.
  • For instance, when creating a new ".mac" file at the Maxima level, the file itself must be creator with the correct author, copyright notice, load and doxygen commands for that file, as well as the appropriate test and testobjects files again with the appropriate data inside. Much of these files could be automatically generated with a single command.
  • There is also the possibility that information (such as the location of the author) or the inclusion of the files in the "include.mac" file, although not automatically generated, could be suggested to the user of the command as the command completes.

Definition in file general.hpp.