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)¶
Create a new directory
RISC/foo
.Your package code goes into
RISC/foo/foo.m
. (Yes, same name as directory.)Your test code goes into
RISC/foo/foo.mt
. (Yes, same name as directory.)Create a file
RISC/foo/foo.rst
to document your package. (Yes, same name as directory.)Put
foo
as a separate line into the filepackages.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
andRISC/foo/baz.m
. StillRISC/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 aModule[]
. In particular, every variable that appears in the variable list of aBlock[]
should be listed here.
The test code (.mt file)¶
You can put your tests into several .mt files.
Each .mt file has the following format:
(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.
(optional) The definition of a setup function that is run before each single test. Its form is:
SetUp[] := (* code goes here *)
(optional) The definition of a tear down function that is run after each single test. Its form is:
TearDown[] := (* code goes here *)
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 theTest
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 ofZb
should rather live in a .mt file in the directoryRISC/fastZeil
, since it exclusively tests thefastZeil
functionality and has nothing to do withRISC/Engel
.Each .mt file is run in a separate Mathematica process.
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
andFILE2.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 likevi
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.