README.developers-howto

   1   Maxima project Git / build system HOWTO
   2
   3
   4   1  General
   5
   6       Makefile.am is the file to modify, NOT Makefile
   7       (Makefile is generated automatically from Makefile.am)
   8
   9       "make install" catches Makefile problems
  10       that are not detected by "make" alone
  11
  12       Adding / removing files often leads to Makefile problems
  13
  14       To update your repository, execute
  15       git pull  # assuming origin/master points to the SF Maxima repo
  16
  17       Workflow with Git:
  18       git pull                      # update your repo
  19       git checkout master           # work off master
  20       git checkout -b scratch-pad   # create a working branch
  21       <do development, tests, commits, then, once satisfied...>
  22       git checkout master           # put yourself on master branch
  23       git pull                      # update your repo, again
  24       git merge scratch-pad         # merge development work into master
  25       git push origin master        # push to SF Maxima repo
  26
  27       BE SURE NOT TO PUSH YOUR SCRATCH-PAD!
  28
  29   2  Renaming something in Git
  30
  31       --  Create a scratch/development branch as in 1.
  32
  33       --  git mv X Y
  34           This moves X to Y and preserves the history.
  35           Like any other change, this needs to be committed
  36           as a separate step.
  37
  38   3  Adding / removing a file in maxima/src
  39
  40       --  Create a scratch/development branch as in 1.
  41
  42       --  Add new file X, then execute
  43           git add X; git commit -m 'Message' -- X
  44
  45       --  Remove old file X
  46           git rm X
  47           Then execute "git commit" as above
  48
  49       --  Add / remove file name from maxima/src/Makefile.am
  50
  51       --  Add / remove file name from maxima/src/*-depends.mk
  52
  53           NOTE: There are several *-depends.mk files. These are
  54           theoretically updated automatically but to the best
  55           of my knowledge it is necessary to fix them by hand.
  56
  57       --  Add / remove file name in maxima/src/maxima.system
  58
  59       --  Verify that
  60           "sh bootstrap; ./configure --enable-foolisp; make; make install"
  61           and "run_testsuite();" all succeed
  62
  63       --  Merge your work onto master and push the changes as in 1.
  64
  65
  66   4  Adding / removing a file in maxima/share
  67
  68       --  Copy new file / remove old file
  69           as you did in 3.
  70
  71       --  Add / remove file name in maxima/share/Makefile.am
  72
  73       --  Verify that
  74           "sh bootstrap; ./configure --enable-foolisp; make; make install"
  75           and "run_testsuite();" all succeed
  76
  77       --  Merge your work onto master and push the changes as in 1.
  78
  79
  80   5.1  Creating a new share package
  81
  82        E.g., new package name = my_package
  83
  84       -- Naming conventions:
  85
  86          write_long_names_like_this, andNotLikeThisPlease,
  87          norlikethiseitherthanks
  88
  89          spell_out_names, dnt_try_sv_typng_w_abbrvs_tnx
  90
  91       -- Create a new directory my_package
  92
  93       -- Put Lisp and/or Maxima files in the directory
  94
  95          At least one file must be named my_package.lisp or my_package.mac
  96          Otherwise load(my_package) fails
  97
  98       -- Create texinfo documentation file my_package.texi
  99          (PLEASE CREATE DOCUMENTATION, THANK YOU)
 100
 101          my_package.texi goes in maxima/doc/info
 102          (same as other texinfo files)
 103
 104          Use maxima/share/template.texi as a template for my_package.texi
 105
 106       -- Create test file rtest_my_package.mac
 107          (PLEASE CREATE A TEST FILE, THANK YOU)
 108
 109          Test file contains pairs of expressions:
 110          input expression, then expected result
 111
 112          batch("my_package/rtest_my_package.mac", test);
 113          executes the test
 114
 115
 116   5.2  Adding a directory in maxima/share
 117
 118       --  Create a scratch/development branch as in 1.
 119
 120       --  Make the new directory and put the new files in it
 121
 122       --  Add the all the files in your new directory and commit this change:
 123           git add .
 124           git commit -m 'Message' -a
 125
 126       --  Put the my_package files on the file list of maxima/share/Makefile.am
 127
 128       --  Add my_package to SHARE-SUBDIRS-LIST in maxima/src/init-cl.lisp
 129
 130       --  Move my_package.texi to maxima/doc/info
 131
 132           Put my_package.texi on the list of files in
 133           maxima/doc/info/Makefile.am
 134
 135           Put my_package on the list of topics in maxima/doc/info/maxima.texi
 136           See instructions in comments at top of maxima/share/template.texi
 137
 138       --  Verify that
 139           "sh bootstrap; ./configure --enable-foolisp; make; make install"
 140           and "run_testsuite();" all succeed
 141
 142       --  Commit and push your work as in 1.
 143
 144
 145   6  Adding / removing a file in maxima/tests
 146
 147       --  Create a scratch/development branch as in 1.
 148
 149       --  Copy new file / remove old file
 150           and execute "git add" / "git rm"
 151
 152       --  Add / remove file name in maxima/tests/Makefile.am
 153
 154       --  Add / remove file name in maxima/tests/testsuite.lisp
 155
 156       --  Verify that
 157           "sh bootstrap; ./configure --enable-foolisp; make; make install"
 158           and "run_testsuite();" all succeed
 159
 160       --  Commit and push your work as in 1.
 161
 162
 163   7  Updating the website
 164
 165     See the Git module "site-xml", particularly "README" there.
 166
 167
 168   8.1  Backups of Git
 169
 170     All you need is the rsync tool and some disk space.
 171
 172     Issue the following command:
 173
 174     rsync -av 'rsync://maxima.git.sourceforge.net/gitroot/maxima/*' .
 175
 176
 177   8.2  Backups of the ML subscribers list
 178
 179     You need to be a list admin to do that. Other then that you only
 180     need a mail client to send mailman commands to
 181     maxima-request@math.utexas.edu
 182
 183     The command to get the subscribers list is "who" followed by the
 184     list admin password. Sending an empty mail with "who XXX" in the
 185     subject line should be enough.
 186
 187     I have the following cron.weekly script to do this automatically:
 188
 189     | #! /bin/sh
 190     |
 191     | su myuser -c "echo end | mail -s \"who password\" maxima-request@math.utexas.edu"
 192
 193
 194   8.3  Other Backups
 195
 196     Backups of the following stuff would be nice too:
 197
 198     - wiki
 199
 200     - bug database