mercurial is a source management system developped by Matt Mackall: http://www.selenic.com/mercurial/ 0. prerequisites ---------------- - linux or cygwin - python 2.3 or newer (run "python -V" to see which version you have installed) - yalmip on your matlab path. yalmip is not included in the MPT repository anymore, rather you have to download the recent version from official site: http://control.ee.ethz.ch/~joloef/yalmip.php 1. installation of mercurial ---------------------------- http://www.selenic.com/mercurial/README - download the latest release from http://www.selenic.com/mercurial/mercurial-snapshot.tar.gz - unzip and untar the archive: $ gzip -d mercurial-snapshot.tar.gz $ tar xvf mercurial-snapshot.tar - cd to the newly created directory: $ cd mercurial-snapshot - decide where you want to install it. if you have root priviliges (cygwin has this automatically), then you can do a system-wide installation: $ python setup.py install - if you want to install locally (typically in restricted linux environment), first create the following directory: $ mkdir ~/bin - now you can install mercurial into your home: $ python setup.py install --home=~ $ export PYTHONPATH=${HOME}/lib/python $ export PATH=${HOME}/bin:$PATH - after installation, try if mercurial works by calling: $ hg if you get complaints about missing modules, you probably haven't set PYTHONPATH correctly. 2. setting up local copy of MPT repository ------------------------------------------ [sidenote] my preference is to have a main directory called "mpt", under which i create another directories, each of them corresponding to one project. so my directory structure looks like this: mpt/ - main directory, does not contain any files mpt/mpt - mirror of MPT's main line mpt/mpt-lp - work on LP solvers is done here mpt/mpt-prestab - work on feedback prestabilization is done here mpt/mpt-testing - all changes i am not sure about are first tested in this directory, such that i do not polute the mainline with garbage so assume you want to work in the similar manner as i do: - create main mpt directory $ mkdir mpt - checkout the latest mainline version: $ hg clone http://control.ee.ethz.ch/~mpt/hg/mpt/ this will create a new directory called "mpt", which now contains the latest version of MPT [sidenote] if you have multiple directories as i do, you often would like to switch you matlab path from one setup to the other one. i have written a small script which does this, it is available at: http://control.ee.ethz.ch/~mpt/hg/mk_init.m before using it, edit the line which says: MAINDIR = 'c:\matlabfiles\mpt'; point the MAINDIR variable to your main "mpt" directory, i.e. the one which contains "mpt", "mpt-lp", "mpt-prestab", etc. directories. when you start the script, it will search your main directory for subdirectories and will subsequently allow you to choose one of them. after your choice is made, mk_init will: 1. remove any mpt directories from current matlab path 2. add your desired choice to the current matlab path (including all sub-directories) 3. call mpt_init for more questions on this script feel free to bug me by personal email. 3. stay up-to-date with the latest version ------------------------------------------ - change to the directory which contains your local copy of MPT: $ cd mpt/mpt - pull latest changes: $ hg pull - what pull does is it loads recent changes from the web, but your local files are not modified yet. to bring your local files up-to-date, call: $ hg update - if you haven't made any changes to your local copy, the update will work nicely. if there are any conflicts, you have two ways to go: 1. overwrite your changes with the official version: $ hg update -C 2. merge your changes with the official version (can lead to even more conflicts, so you should really know what you are doing): $ hg update -m 4. developing MPT ----------------- if you want to modify any function, it's best to create a separate directory for this purpose. let's assume you want to make some changes to the MPLP solver... you would create a clone of your local mirror of the official version first: $ ls mpt $ hg clone mpt/ mpt-mplp this will create a directory "mpt-mplp" which is a clone of your local clone of the official repository. now do the development in the "mpt-mplp" directory, and once you are happy with the state of your work, you can send it to me: $ hg diff > mplp.patch once you generate the patch, send it to me as an attachment (do not include the patch directly to the mail body!), and include a brief description of your changes. now wait for me to accept the patch and to propagate it to the mainline. once it's there, you can pull from the mainline, update your main "mpt/" copy and check if your changes have been included properly. now you can throw away your "mpt-mplp" working directory... there are many alternative ways of getting your changes back to me: 1. you can commit your local changes to your local "mpt-mplp" tree by running $ hg commit -m "your log message" and, at the end, using: $ hg export revision > mplp.patch where "revision" is the revision number on which you started to work. you can then send me the patch by email. 2. you can commit your local changes and make them available through web: $ hg serve -p 8080 now you can navigate to http://localhost:8080/ to see history of your working tree. quickly send me hostname of your machine such that i can pull directly from you. 5. browsing history through web ------------------------------- there is an on-line history of MPT going back to April 15, 2005 available at: http://control.ee.ethz.ch/~mpt/hg/mpt/ you can browse through individual changes, see what was changed and who did the changes. i would like to draw your attention to the upper-left corner of the web page where you will find many interesting buttons - for instance you can subscribe to MPT's RSS feed and be informed about recent modifications made to the mainline. there are more trees available on-line, you can find them from: http://control.ee.ethz.ch/~mpt/hg/ the other trees are just temporary, and serve the purpose of testing. usually my changes are first propagated to "mpt-testing" or to "mpt-sandbox", and even after they are tested, i push them also to "mpt" mainline repository.