Notes for Authors

Getting the Sources

How to Get Access

Send your ssh public key $HOME/.ssh/gitolite.pub to the gitolite maintainer. If you do not find that file, you can create it via

ssh-keygen -t rsa -f $HOME/.ssh/gitolite -C YOURNAME@gitolite

You should enter a passphrase for your key. It should be strong. Make sure your $HOME/.ssh directory and your key are only readable by you. No right for “group” or “other”!

Put the following lines into the file $HOME/.ssh/config. (Yes, you should write git (sic!) as the user.)

host gitserver
  IdentityFile ~/.ssh/gitolite
  HostName git.risc.jku.at
  User git
  HostbasedAuthentication no

Then execute the following command to make sure the config file is only readable by you.

chmod 600 $HOME/.ssh/config

One Time Preparation to Get the Sources

You must have git available. Install if necessary.

sudo apt-get install gitk

If in the output of git config --list you don’t find something like

user.name=FirstName LastName
user.email=YourFirstName.YourLastName@risc.jku.at

, then you should introduce yourself to git. This will create/modify a file ~/.gitconfig.

git config --global user.name "YourFirstName YourLastName"
git config --global user.email "YourFirstName.YourLastName@risc.jku.at"

You should use your default email address. This email address is only used by git to identify you, but not to send any mail to you.

How to Get the Sources

The sources are stored in a git repository. Run

git clone gitserver:private/hemmecke/ergosum

This will create a directory ergosum on your local computer with the sources of all combinatorics packages.

Development

Make sure you have performed the initial steps from Compiling a Distribution, in particular:

cd /path/to/ergosum
./build-setup.sh
./configure
make uninstall install PREINSTALLEXT=mma

This will install an unencrypted version into $HOME/.Mathematica/Applications.

Note

The above steps have to be performed whenever either Makefile.am or packages.list has been modified.

Now you can follow Section Creating a new package.

People who love Emacs might be interested in using a special emacs-mode.

Creating a new package (foo)

  1. Create a new directory RISC/foo.

  2. Your package code goes into RISC/foo/foo.m. (Yes, same name as directory.)

  3. Your test code goes into RISC/foo/foo.mt. (Yes, same name as directory.)

  4. Create a file RISC/foo/foo.rst to document your package. (Yes, same name as directory.)

  5. Put foo as a separate line into the file packages.list in order to let the build system know about your new directory.

The main package code (.m file)

  • You can split your package over several .m files like RISC/foo/foobar.m and RISC/foo/baz.m. Still RISC/foo/foo.m would be the main entry point. The other packages would be loaded using << "RISC`foo`foobar`" (with or without double quotes).

  • The structure of your packages is as follows:

    BeginPackage["RISC`foo`", {"RISC`RISCComb`"}];
    
    (* Specify the minimal Mathematica version to run the package. *)
    Needs["RISC`Version`"]; RISC`Version`RequiredMathematicaVersion[5.2];
    
    Needs["RISC`LinSolve`"]; (* optionally needed packages *)
    
    `ExportedFunc1::usage = "API description here";
    `ExportedFunc2::usage = "API description here";
    
    Begin["`Private`"]
    UserDefinable = {"pubfoo1","pubfoo2"};
    PrivatelyModifiable = {"privfoo1", "privfoo2"};
    
    (* !!! Code goes here !!! *)
    
    Needs["RISC`Copyright`"];
    Copyright[
      "Package foo version x.y",
      "written by Ralf Hemmecke",
      "Copyright Research Institute for Symbolic Computation (RISC),",
      "Johannes Kepler University, Linz, Austria"];
    End[]
    EndPackage[]
    
  • UserDefinable is only needed for identifiers that you want allow the package user to change.

  • PrivatelyModifiable is only needed if your code modifies variables that are not local to a Module[]. In particular, every variable that appears in the variable list of a Block[] should be listed here.

The test code (.mt file)

  1. You can put your tests into several .mt files.

  2. Each .mt file has the following format:

    1. (optional) At the beginning of the file a list of prerequisites is given for running the tests. There should be several lines of the form:

      << RISC`baz`
      

      Each of these packages will be loaded before a test is evaluated. It is only necessary to mention the additional packages that are needed in during the test. The current package is loaded in any case.

    2. (optional) The definition of a setup function that is run before each single test. Its form is:

      SetUp[] := (* code goes here *)
      
    3. (optional) The definition of a tear down function that is run after each single test. Its form is:

      TearDown[] := (* code goes here *)
      
    4. A list of tests of the form:

      Test[
        (* command to run *)
        ,
        (* expected output *)
        ,
        (* optional list of expected messages *)
        ,
        (* optional list of options *)
      ]
      

      See RISC/Testing/Testing.m for a more detailed specification of the Test arguments.

    Example for RISC/Engel/SomeTest.mt:

    (* Since the test is in the directory RISC/Engel, the package
       RISC`Engel` is loaded automatically. *)
    (* Packages that must be additionally loaded. *)
    << RISC`fastZeil`; (* Needed for call of Zb below. *)
    
    (* For testing we make certain private functions public. *)
    SetUp[] := (
      assert          := RISC`Engel`Private`assert;
      AssertionFailed := RISC`Engel`Private`AssertionFailed;
    );
    
    (* Test that a certain exception happens as expected. *)
    Test[Catch[assert[1=!=1],
          AssertionFailed,
          Function[{val,tag},tag]]
        ,
        AssertionFailed
    ];
    
    Test[
        Zb[Binomial[n, k], {k, 0, n}, n, 1]
        ,
        {2*HoldForm[SUM[n]] - HoldForm[SUM[1 + n]] == 0}
    ]
    

    Usually, tests should only test the functionality of the package in the respective directory, so lines like <<RISC`fastZeil`; are only needed, if a package test requires some functionality from another package. In other words, the test of Zb should rather live in a .mt file in the directory RISC/fastZeil, since it exclusively tests the fastZeil functionality and has nothing to do with RISC/Engel.

  3. Each .mt file is run in a separate Mathematica process.

  4. The tests in each .mt file is run in one Mathematica process, but with all variables reset.

The web documentation (.rst file)

RISCErgoSum is documented via ReStructuredText files and then compiled with Sphinx.

  • For a package foo one would write a page with the following structure.

    A Mathematica implementation of Foo-theory
    ==========================================
    
    Short Description
    -----------------
    
    ``Foo`` is a Mathematica implementation of the well known
    Foo-theory. It also implement the Foolish variant of the main
    algorithm.
    
    
    Author
    ------
    
      * `John Doe`_
    
    Accompanying files
    ------------------
    
      * `foo-demo.nb`_
    
    
    Literature
    ----------
    
      * X. FooBar
        **The Foo-Theory**,
        Journal of interesting Mathematics, Vol. 7, pp. 22-67,
        PubLi Shing House, 2000.
        `[pdf] <http://www.example.com/foo.pdf>`_
    
    .. _John Doe: http://en.wikipedia.org/wiki/John_Doe
    .. _foo-demo.nb: foo/foo-demo.nb
    
  • Note that the main title is to be underlined using equal signs (=). For subsections minus signs (-) are used.

  • A download link will be generated automatically.

Compiling, Testing, Installing

See Compiling a Distribution for more detail.

How to work with GIT

It is usually enough to work with the following git commands:

git pull

Get the latest changes from the official repository.

git add FILE1.mt FILE2.m

Mark FILE1.mt and FILE2.m to be committed in the next commit.

git commit

Commit all marked modifications to the local repository.

Note that only files that have been added via git add will be committed.

Note that after git commit the modifications have not yet left your computer. They are simply stored in your local repository.

Set the variable GIT_EDITOR in your $HOME/.bashrc if you don’t like vi so much.

export GIT_EDITOR="emacs -nw"
git push

Upload your modifications to the official repository.

git status

Investigate which files have changed on your file system.

git log

Investigate the history of changes.