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 :ref:`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 <#creating-a-new-package-foo>`_. 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 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) ------------------------ #. 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 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 ``<`_ 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] `_ .. _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 :ref:`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. .. seealso:: * `The ProGit Book `_ * `Use gitk to understand git `_