Developer resources - Project LinBox

On this page are instructions for developers and those wishing to contribute to LinBox. It is intended both for the uninitiated and for the reference of existing developers.

Table of Contents

1. Compilation and installation
2. Basic layout
3. git
4. Coding standards
5. Checklist for adding files
6. Website maintenance

Compilation and installation

See the documentation. Quick link to the tarball and git installation notes. If you are installing from the git repository (https://github.com/linbox-team), please continue reading the instructions in the git section below.

Basic layout

LinBox is a template library, so installation requires very little actual compilation. Nearly all of the library is in header files. Directories in the source distribution are as follows, relative to the tree's root:

N.B. Though the doc/ directory contains some top-level and tutorial documentation, reference documentation is stored in parallel with the source code, under the src/ tree.

git

LinBox is a project maintained at github.com. To access the latest bleeding edge copy of LinBox from this source, you will need a working copy of git and all of the GNU development tools (e.g. autoconf, automake, GNU make, and so on).

1. Make sure you have the necessary tools installed

   You will need GNU Autoconf, GNU Automake, and GNU Libtool. Make sure the bin directories of these tools are in your PATH, e.g. if you have Libtool installed in /usr/local/algebra/libtool, make sure /usr/local/algebra/libtool/bin is in your PATH.

   Also, if Automake is installed in a place separate from Autoconf, you will need to set the environment variable ACLOCAL_FLAGS to "-I <automake prefix>/share/aclocal", where <prefix> is the install prefix of Automake. Similarly, if Libtool is installed to a separate prefix, you should add "-I <libtool prefix>/share/aclocal" to ACLOCAL_FLAGS, where <libtool prefix> is the install prefix of Libtool.

   See http://www.gnu.org/software/autoconf/ for GNU Autoconf, http://www.gnu.org/software/automake/ for GNU Automake, and http://www.gnu.org/software/libtool/ for GNU Libtool.

   GNU Autoconf, GNU Automake, and GNU Libtool are only required for checkouts from the git repository. But whether you are installing from a tarball release or from an git revision, the packages on which LinBox depends will be needed: the GNU multiprecision library (GMP), Givaro, fflas-ffpack, and a BLAS implementation, optionally NTL.

2. Check out the LinBox project source code from the trunk of the repository

   git clone https://github.com/linbox-team/linbox

3. Switch to the newly-created linbox directory and run the script autogen.sh, optionally specifying the installation prefix:

   cd linbox
   ./autogen.sh [--prefix=<prefix>] [options]

   [options] include the following:

   --with-gmp=<gmp-prefix>	Prefix of your GMP installation
   --with-blas=<blas-prefix>	Prefix of your BLAS installation	There is an ATLAS variant.
   --with-givaro=<givaro-prefix>	Prefix of your GIVARO installation
   --with-fflas-ffpack=<fflas-ffpack-prefix>	Prefix of your FFLAS_FFPACK installation
   --with-ntl=<ntl-prefix>	Prefix of your optional NTL installation
   --with-lapack=<lapack-prefix>	Prefix of your optional LAPACK installation

   For each package, this specification is needed only if the package is not installed at a standard location such as /usr or /usr/local. It is also necessary to set your LD_LIBRARY_PATH to support dynamic linking with the lib directory of any of the packages installed in a nonstandard place.

4. Install the library:

   make install

When you want to update your tree with the contents of the LinBox Git repository, issue the following command from the linbox/ directory:

git pull

You should receive some information on what files have been updated. If any files have a "C" before them, this means what you have conflicts with what is in the repository. In other words, you made changes while someone else made other changes and git does not know how to reconcile the two. You will need to edit that file manually, looking for and fixing lines like

<<<<<<<<<<<

===========

>>>>>>>>>>>
	  

that show the sections that could not be reconciled.

If you have made changes and would like to commit them to the global repository, use

git add [<filename(s)>]

git commit -m "<useful log entry>"

git push

The optional filename(s) argument specifies what you would like to commit; the default is to commit everything that has changed in the current directory and its descendents. When you enter this command, a text editor will come up prompting you for a log message. ALWAYS ENTER A LOG MESSAGE DESCRIBING WHAT YOU HAVE CHANGED. Failure to do so may result in your changes being backed out by the administrator. When you are done entering your message, simply save and exit the text editor.

If you are not a main LinBox developer but would like to submit some addition or modification, your code is welcome. Please email a patch (use 'git diff' to form a patch) to us and we will consider including it. Or, even better, attach your patch to a ticket in our Trac database.

Coding standards

1. Indentation style

   We use the Linux indentation style, i.e. K&R with 8-space indents. We would like to keep this standard, so please use it for any code submitted to the project. Here is an example:

   void myFunction (int a, int b, int c)
   {
   	int d;
   
   	if (a == 0) {
   		d = 1;
   	}
   	else if (a == 1) {
   		d = 2;
   		myOtherFunction (b, c);
   	} else {
   		d = 3;
   	}
   }
   
   template <class T>
   class MyClass : public MyOtherClass {
   	int _b;
   
       public:
   	MyClass (int a)
   		: MyOtherClass (a), _b (0)
   	{
   	}
   };
   	      

   If you are using Emacs, then the text editor may automatically try to use its default GNU coding style when auto-indenting. This yields code that is very hard to read. To fix this problem, all files in LinBox should start with the following line:

   /* -*- mode: C++; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */

   Also, to make Emacs default to the more reader-friendly Linux indentation style, add the following to your ~/.emacs file:

   (add-hook 'c-mode-common-hook
   	  (lambda ()
   	    (c-set-style "linux")
   	    (c-set-offset 'access-label '/)
   	    (c-set-offset 'inline-open 0)))
   	      

   One more note: as stated below all LinBox files are declared in the namespace LinBox. This causes Emacs to indent all of the source code an extra level. We consider this to be excessive, so the preferred approach is to force Emacs not to indent for that namespace declaration. To do this, just go to the first few lines inside the namespace and pull them back to the first column. Emacs will follow that pattern from there on out.

2. Naming conventions

   We use Java/Smalltalk conventions for naming classes, methods, and variables. Classes whose names have several words have all the words juxtaposed without underscores, and each word has its first letter capitalized (e.g. MyClass, MyOtherClass). Methods are similar, except that the first letter of the first word is lower case (e.g. myMethod). Global constants should be all upper case with underscores between the words (e.g. MY_CONSTANT). In addition, variables that are members of classes should begin with an underscore to differentiate them from methods and parameters (e.g. int _myMember; int myMember () const;).

   Directory and file names should be in lower case, with words separated by a hyphen ('-'), e.g. my-file.h

   We generally avoid abbreviations so as to avoid confusion among users of the library. However, some very commonly used features are abbreviated and some words commonly used together are treated as a single word. For example, we use "minpoly" rather than "MinimalPolynomial" and "Blackbox" rather than "BlackBox".

3. Miscellanae

   We put all of our declarations in the namespace LinBox. Please put the lines

   namespace LinBox
   {
   
   ... // Your code here
   
   }
   	      

   in all header files of contributed code.

   All header files should have a set of preprocessor directives to prevent multiple inclusion. If your header file is named my-header-file.h, use

   #ifndef __LINBOX_my_header_file_H
   #define __LINBOX_my_header_file_H
   
   ... // Your code here
   
   #endif // __LINBOX_my_header_file_H
   	      

   surrounding the whole file, except possibly any comments you have at the top.

   All files should contain a comment at the top indicating the file name, copyright, authors, and licensing. Additional documentation would be useful. You may use any of the files in this library as a template.

   Key objects must have documentation comments to be processed by doxygen in the creation of our online documentation system. In the reference manual, see the section documenting doc itself for guidelines on these comments.

Licensing

This code is licensed under the GNU Lesser General Public License (see COPYING for details); all contributed code should be similarly licensed. We cannot accept any code that is released under a license legally incompatible with the LGPL, so please either license the code under the LGPL or explicitly place it in the public domain if you are unsure. Technically, code released without a license at all and not explicitly placed in the public domain is incompatible with the LGPL, so licensing it is important.

Intellectual property

The original author of a program holds the copyright to that program. If another author changes the program, the changes are copyrighted to that other author provided that in the preamble a change is announced and that the places where the changes are made are annodated by the initials of the author and a date.

Checklist for adding files

The procedure for adding a file is based on the type of file being added.

Adding header files

In the text below <filename> refers to the file you are adding and <dir> refers to the directory where the file you are adding is located.

1. Make sure the file has the correct format, with the author's name and a copyright and license notice at the file's top. Also make sure it follows coding standards to the best of your ability.
2. Open <dir>/Makefile.am and locate the list that starts with include_HEADERS. Add your file to that list. If you add it to the end of the list, make sure the preceding line ends with a backslash '/'.

3. For major changes only: Add an entry to linbox/ChangeLog detailing the IDEAS that are different in LinBox's architecture or implementation as a result of your change.

   Small modifications, file renamings, and so on do not deserve entries in the ChangeLog -- details like that can be seen at the Trac site.

4. Add the file with git and check it in to the github master. Please strive for a meaningful, useful log entry.

Adding a test

All tests should go in the directory tests. They should be in the form of a standalone program that can run a sensible test with no command line arguments, preferably with a name prefixed by "test-". In the text below, <test> refers to the name of your test binary, e.g. test-minpoly. <mod-test> refers to the result of replacing all "-" and "." characters in <test> with an underscore "_". <test-source> refers to the name of the source file; the procedure works just as well if you have multiple source files. By convention, the name of the source file should be <test>.C

1. As above, make sure the file has the correct format.
2. Open tests/Makefile.am. Add <test> to the line that starts with "BASIC_TESTS = ".
3. You will see a list of blocks that look like:

   test_sparse_matrix_SOURCES = 		\
   	test-0-matrix.C			\
   	test-common.C	test-common.h
   	      

   Below the last such block, add a block of the following form:

   <mod-test>_SOURCES = 		\
   	<test-source>		\
   	test-common.C	test-common.h
   	      

4. Add the file with git and check it in to the github master. Please strive for a meaningful, useful log entry.

Website maintenance

• The website repository is the www branch of linbox-team/linbox on github.com, https://github.com/linbox-team/linbox/tree/www
• The website is served from linalg.org:/var/www/linbox/, which is a checkout from the repository.
• To modify the website, checkout an instance of the www branch, make your changes and commit/push. They automatically propagate to the public website.
• When updating the website, please also make an up-to-date version of the html documentation. In a linbox installation, make the html docs and copy the linbox-html directory to the website.
  1. cd <path>/linbox/doc
  2. make docs
  3. scp -R linbox-html linalg.org:/usa/www/usa/linbox/public_html
     (Use your own linalg.org account pw.)
• Google analytics is being tried. Paste analyticstracking.html in each new html file header.