FAQ

General philosophy

• Why do we build all these external sources?
  1. One major goal of the OKlibrary is reproducibility, that is, given the ID of the repository, all experiments performed using the OKlibrary should be reproducible. This needs a tight control over the environment.
  2. So we make a separation between "sources important for us", which we install, and "background sources", where we don't expect different versions to make a difference, and we don't install them, but require them from your Linux distribution.
  3. Running-times are also important to us, and they depend on the compilers and libraries used.
  4. Furthermore, just building and running the many external sources we use creates a network of complex requirements. Packages sometimes work only with other packages with a special version-number, and many packages we use are not included in any Linux distribution
  5. Often we (need to) improve/correct the packages.
  6. Another system which (like the OKlibrary) needs to install many and diverse "external sources", the SAGE computer algebra system, also installs all components like compilers etc. itself --- there is no alternative.
  7. If a user experiences problems, we wouldn't have any chance finding out what goes on if major software wouldn't come from the OKlibrary.
  8. Finally, we anyway need a strong system for installing external sources for the many non-standard sources we install (e.g. SAT/CSP etc. solvers).
• Can I adjust the build system?
  1. The build system of the OKlibrary is designed as an open system.
  2. So in principle nearly everything can be adjusted by changing certain variables of the build-system (typically make-variables).
  3. However this can also create problems nearly impossible to spot, for example just forgetting certain special settings.
  4. And problems will arise in case of some update.
  5. So you need to know what you are doing, that is, you need to explore the system in greater depth --- starting yourself.

Installation

• What to do in case of a build-error?
  1. Often clearly some package is missing.
  2. Otherwise, in the directory OKlib/Buildsystem/ExternalSources/SpecialBuilds/plans there are plans regarding all the external sources we build, and if we are aware of some build problem, then we discuss it there.
  3. Before re-building, first everything must be cleaned:
     • If you were just using "oklib all", then use "oklib cleanall", and start again.
     • If you were building a special target "XXX", i.e., you used "oklib XXX", then use "oklib cleanallXXX" (no space!), and start again.
• The links in the public bin-directory do not work?
  1. In OKplatform/bin you find links to the main executables produced by the OKlibrary.
  2. However, some may not work (since they actually point to an empty target).
  3. The problem here is, that these programs first need to be built, either by compilation from the OKlibrary itself, or by building an external source.
  4. These build-processes then will provide the target for the links.
  5. Building happens mostly by oklib all (in directory OKplatform/OKsystem, for the programs provided by the OKlibrary itself).
  6. Some programs are provided by external sources, and then these external sources need to be built, by the appropriate oklib external-source (in directory OKplatform/ExternalSources).
  7. In order to create links which were introduced after the initial building of the OKlibrary, use oklib --prebuild.

External sources

• Why do we provide gcc-4.1.2 ?
  1. We have a fixed gcc-version, namely 4.1.2, and a current version, rather close to the newest gcc-version. Why this?
  2. Consider the evolution of C++:
     1. The first real C++ was C++98; before this first ISO standard, many versions floated around.
     2. Fixing problems we get C++03, a minor revision.
     3. C++09 now is a major revision, also extending the language. It is not yet fully realised by Gcc.
     4. C++1X will further introduce major features.
  3. A great thing about C++ is the strength of the standard (the "bible"), and all major C++ compilers moved (and are still moving) towards greater standard compliance.
  4. But only now (2011) are the major compilers in a state that standard-conforming C++03 can be written --- it's the compiler who tells you what is correct and what not!
  5. So there is a lot of C++ code out there with many weaknesses.
  6. One of the goals of the OKlibrary is to build up over time a repository of "historic solvers", and those won't compile with newer compiler versions.
  7. And if C++ code is not actively maintained, it will likely stop compiling at some point.
  8. Currently the OKlibrary itself does not build with gcc version 4.2.1 or later, due to the use of non-standard template mechanisms (we weren't aware of). We are waiting now for features of C++09 to be included, so that the repair becomes easier.
  9. Gcc version 4.1.2 seems to be a watershed --- starting with version 4.2.1 a major push towards only providing standard C++ took place (which is a good thing), while version 4.1.2 is the most stable version supporting most of the old non-standard features.
  10. Perhaps at some point in the future we need three gcc compiler-versions (no problem with the flexible build-system of the OKlibrary).

Problems running programs

• Runtime linking problems ("libraries not found"):
  1. We experienced problems with Suse (Linux) distributions, and we found that system-wide installation of the package binutils-2.20.tar.bz2 (available in ExternalSources/sources/LinuxTools) solved the problems (although the Suse-installed linker had in one case the same major version number, nevertheless it produced unnecessary runtime-links which caused problems).

The documentation system

• In the plans directories, all the files are .hpp-files, that is, C++ files?
  1. Most parts of the documentation system are created using Doxygen.
  2. The .hpp-files in plans-directories do only contain C++ comments, but no actual code.
  3. And inside the comments the Doxygen-directives are placed, which describe documentation (and plans, discussions, etc.).
  4. The Doxygen-system then creates the html-pages.
  5. Only some html-pages, like this one, are directly created in the html-format, while otherwise we use the Doxygen-system for formatting, and, perhaps most important, for link creation.

How to find something

• Perhaps you want to find whether we implemented something from a paper of author XYZ, or you changed the location of file DIR/FILE, and you need to change all references to that file. Just search for TEXT (=XYZ resp. =DIR/FILE) by the tools provided by Linux (and possibly your distribution). Most basic is grep:

  OKplatform> grep -rl "TEXT" *
      

  (where "r" is for "recursive descend" and "l" for "print only file-names", while the filename expansion "*" at the end invokes all files and directories in the working-directory).
• I (OK) am using for example xemacs, which produces backup-files marked through the suffix "~"; normally you want to exclude such files, and then you can use a find-filter:

  OKplatform> echo $(find * -not -name "*~" -and -type f) | xargs grep -rl "TEXT"
      

• Using find is very powerful, however just for excluding a filename-pattern we can use grep, and the following command has the same effect:

  OKplatform> grep -rl --exclude="*~" "TEXT" *
      

  And if you only want to search for plans-files, then you can restrict the search to files with suffix ".hpp" by

  OKplatform> grep -rl --exclude="*~" --include="*.hpp" "TEXT" *
      

  (but these filename-patterns only work for the basename; if you want to control the full path, then you need to use the more powerful find-filter).
• Another useful option of grep is "i", for example in the form grep -rli, which means that the search pattern matches in a case-insensitive manner (useful if you are not sure about the precise usage of small and capital letters in the pattern, or if you want to capture several such patterns.

Last modified: Sat Oct 29 20:43:48 BST 2011