next up previous contents
Next: How to use the Up: Introduction Previous: Conventions used in this   Contents

How to add your contributions to future GRASP releases.

As we have explained, the general idea of GRASP is to have a collection of documented and tested code available for use by the gravitational-wave detection community. Many people have made significant contributions to this package, and we would welcome any additional contributions.

In order to minimize the effort involved in making additions to GRASP, and in order to ensure that they are properly included and available to all, here are some guidelines about how to contribute:

If you want to make "small" changes to GRASP, for example to modify a function to add extra functionality, to repair something that is broken, or to add some additional functions in one section, then please do the following:

  1. Provide documentation in the form of a modified file: doc/man_*.tex. I will merge your changes into the general GRASP distribution. For clarity, let's assume that you have added a utility function, and have modified doc/man_utility.tex by adding a description of your function(s) to it. Remember, software can never be better than its documentation.
  2. In any modifications of the documentation *.tex files, please be sure to spell-check the files before you send them to me. Use either the spell or ispell utilities, or some other alternative.
  3. You should provide additional lines to add to doc/make_tex_from_C. This is a script that automatically converts any *.c example files that you would like to include in the manual into .tex files. In general, you should have an example program which shows a very simple use of your function.
  4. You should provide any figures which have been included in your "modified" doc/man_*.tex file in postscript: doc/Figures/MYPACKAGE1.ps, doc/Figures/MYPACKAGE2.ps, and so on. Note that the postscript files produced by many plotting packages are excessively large, often several MB. For figures produced from programs like this, it is more efficient to use a bitmap to describe the entire image. Full details of how to produce such bitmaps may be found at
    http://xxx.lanl.gov/help/bitmaphttp://xxx.lanl.gov/help/bitmap. The following extract describes `the easiest way to do bitmapping' using XV:

    ``First display the original figure on the screen somehow (e.g. with ghostview). Then use the `Grab' button in XV to snatch a copy of the displayed image into XV's buffer (after selecting `Grab' you can do this either by clicking the left mouse button on the desired window (which grabs the whole window), or by holding down the middle mouse button and dragging (which selects a region)).

    Once the image is in XV's buffer, you can manipulate it. You should use `Autocrop' or `Crop' to remove any excess margins around the figure. Then save it (as gif, jpeg, color postscript or greyscale postscript). If resaving as postscript you must click the XV `compress' box for extra compression.''

  5. You should provide a modified version of (for example) src/utility/utility.c (this modified source contains your additions, merged into the standard GRASP release) and additional example programs demonstrating your functions in
    src/examples/examples_utility/example1.c,
    src/examples/examples_utility/example2.c, and so on.
  6. You should provide a modified version of include/grasp.h (or the additional lines to merge into this header file). This header should contain proto-types for any functions which you have added to GRASP, which you would like to make publicly-available. In general, please try to avoid putting ``documentation" in this header file: it should go into the manual and into the source files.
If you are doing this (modifying or extending existing GRASP functions) please do a search of the existing GRASP source code to verify that your changes do not break existing code. Or, if necessary, make modifications to the existing code, and send me those modified files as well as the materials above.

On the other hand, you might have grander plans! You might not want to make ``small'' changes - you might want to include a major new section in GRASP, for modelling another type of source, or for a type of analysis which is different than anything currently in the package. Let's assume that you want to provide a major new GRASP package or facility called MYPACKAGE. In this case:

  1. You should provide documentation in the form of a file: doc/man_MYPACKAGE.tex, which has the same format as (for example) doc/man_inspiral.tex. I will modify doc/manual.tex by putting a line:
    include{man_MYPACKAGE}
    into doc/manual.tex, to include your contribution to the manual. Reference should be in the same format as the existing ones, and will be added to the references section of manual.tex. Make sure that you modify doc/man_intro.tex to describe any additional directories that you have added to the src tree. Remember, software can never be better than its documentation.

  2. In any modifications of or additions to the documentation *.tex files, please be sure to spell-check the files before you send them to me. Use either the spell or ispell utilities, or some other alternative.
  3. You should provide additional lines to add to doc/make_tex_from_C. This is a script that automatically converts any *.c example files that you would like to include in the manual into .tex files.
  4. You should provide figures in postscript form with names derived from your package name if that is possible. For example: doc/Figures/MYPACKAGE1.ps, doc/Figures/MYPACKAGE2.ps. These figures should be included in your doc/man_MYPACKAGE.tex file.
  5. You should provide source code in src/MYPACKAGE/MYPACKAGE.c and example programs in
    src/examples/examples_MYPACKAGE/example1.c,
    src/examples/examples_MYPACKAGE/example2.c, and so on. The code in
    [4]src/MYPACKAGE/MYPACKAGE.c contains the actual functions that you have provided. Any executable example programs that use these functions should be in the src/examples path.
  6. You should provide a modified header file include/grasp.h or additional lines to merge into this, declaring prototypes for any publicly-available functions.
  7. You should provide ``tail" parts of the Makefiles:
    src/examples/examples_MYPACKAGE/Makefile.tail, and
    src/MYPACKAGE/Makefile.tail. You can see
    src/examples/examples_inspiral/Makefile.tail for an example. Please follow the syntax of this fairly closely: the structure is there for good reasons. If you provide a file that works on your own system it may not work on other people's systems - but if you follow our style it probably will.
  8. Be sure to modify the InstallGRASP utility to include a ``build" in any directories that you have added to the src tree.
In general, the ``rule of thumb'' here is that you should try not to add functions which substantially overlap existing GRASP functions. Either modify the existing GRASP functions (as described below) to add the extra functionality or use them ``as is''.

I would be grateful for a bit of advanced warning about any additions to GRASP (but a uuencoded gzipped tarfile or shar file dropped in my mailbox will get my rapid attention, if it contains these different items, because that makes it easy for me to incorporate it!) The best format for this file is to make it contain only the files that you are adding to GRASP, or those files from the most current GRASP distribution that are being modified, with exactly the correct directory tree structure. This makes it easy for me to unpack your contributions and merge them into the general GRASP distribution. One way to find the absolute ``most current" version of a file is to get it from the GRASP development source tree, which can be reached from
http://www.lsc-group.phys.uwm.edu/$\sim$ballen/grasp-distribution/GRASP/ http://www.lsc-group.phys.uwm.edu/ ballen/grasp-distribution/GRASP/. Before sending me a revised file to incorporate in GRASP, please diff it with the file in this directory, to make sure that the only differences are ones that you have deliberately made!

Note: it is a good idea to check your code in the following ways:

Please remember that many people will be running your code on platforms which are different than yours. The fact that your code runs properly on your platform does not mean that it will run properly on other ones as well. The best way to ensure this is to eliminate the types of problematic constructions that lint and -Wall warn about, and to test your code on a couple of different machines.

One final (important) note. When your code has been sucessfully integrated into the GRASP package, we will issue a new release of GRASP as quickly as possible. As soon as this release is available, we strongly recommend that you throw away your ``personal" working copies of the files that you have been creating or modifying, install this latest release of GRASP, and make new copies of the various files to work from. The reason is this: in the process of including your material into GRASP we have probably made a number of changes to it. If you don't follow our suggestion, make additional changes to your own files and send them to us, we will not be very receptive (as you are forcing us to perform the unpleasant task of merging your changes with our earlier ones).


next up previous contents
Next: How to use the Up: Introduction Previous: Conventions used in this   Contents
Bruce Allen 2000-11-19