Mercurial > forge
changeset 2701:a67d584e6840 octave-forge
developers.in is a derived file. It shouldn't be in the CVS
author | adb014 |
---|---|
date | Mon, 16 Oct 2006 19:13:15 +0000 |
parents | faf6ae737ece |
children | 146b73cf9159 |
files | www/developers.in |
diffstat | 1 files changed, 0 insertions(+), 431 deletions(-) [+] |
line wrap: on
line diff
--- a/www/developers.in Mon Oct 16 19:12:13 2006 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,431 +0,0 @@ -__HEADER__([[[Developer's Notes]]]) - -<h2>Contributing Code to the Gnu Octave Repository</h2> - - -<h3>Requirements</h3> -<p>To contribute your .m files, C++, C, or Fortran code to the GNU Octave -Repository (octave-forge) you need to</p> -<ul> - <li>have an account on SourceForge,</li> - <li>be registered as an octave-forge developer,</li> - <li>have <a href="http://www.cvshome.org/">CVS</a> - installed on the computer from which you - will submit contributions, and</li> - <li>have the secure shell, - <a href="http://www.openssh.com/"><tt>ssh</tt></a>, installed - on your computer.</li> -</ul> -<p>The first two requirements are easy but may take a few days. -If you don't already have one, request a SourceForge (SF) account -<a href="http://sourceforge.net/account/register.php"> here</a>. -To register as a developer send a request -to the octave-forge mailing list -<a href="mailto:octave-dev@lists.sf.net">octave-dev@lists.sf.net</a>. -Include a bit of information about the code -you plan to submit. -Finally, if your computer runs linux or -FreeBSD, chances are good that both <tt>ssh</tt> and CVS are already -installed on your system. -If they aren't, -you will need to find prebuilt packages for them or download their -source codes and build them.</p> - -<h3>Create a SF home directory</h3> -<p> -If you've never submitted code to a SourceForge project before, -create your home directory by -logging onto the octave-forge account with <tt>ssh</tt>:</p> -<pre> - $ ssh -l <span style="color: #800000;"><i>sflogin</i></span> octave.cvs.sourceforge.net - Password: <span style="color: #800000;"><i>your SF password</i></span> -</pre> -<p>Although SF will only show you a message-of-the-day screen then log -you out, this process has the useful side effect of creating a home -directory for you if one doesn't already exist. Some CVS commands will fail -if you do not have a home directory on SF.</p> - -<h3>Download the latest octave-forge distribution</h3> -<p>CVS expects the -code you plan to submit to reside in a directory within the existing -octave-forge directory structure. -You will therefore need to download a copy of the latest octave-forge -distribution to work in. Change directories to a place you want -to put the code, then issue the CVS <i>checkout</i> -(abreviated as 'co') command:</p> -<pre> - $ cd <span style="color: #800000;"><i>working_directory</i></span> - $ export CVS_RSH=ssh - $ cvs -d:ext:<span style="color: #800000;"><i>sflogin</i></span>@octave.cvs.sourceforge.net:/cvsroot/octave co octave-forge -</pre> - -<h3>Where does your code belong?</h3> -<p>Put your file(s) in a subdirectory under the <tt>octave-forge/</tt> -directory. Here are some guidelines to help you decide where your -code belongs:</p> -<ul> - <li> <b><tt>admin/</tt></b><br/> - Contains files and scripts used to administer the octave-forge - website and build the release files. Nothing in here is needed - by octave-forge users. -</li> - <li> <b><tt>doc/</tt></b><br/> - Documentation for octave in general. Documentation for specific - packages goes into the <tt>doc/</tt> subdirectory of the individual package - directories. There are no standards for documentation at this - time. -</li> - <li> <b><tt>extra/</tt></b><br/> - Packages which: - <ul> <li> are too narrow in scope for <tt>main/</tt>, or - <li> act as alternatives for functions in <tt>main/</tt>, or - <li> do not follow octave conventions (because they want - to retain compatibility with matlab for example), or - <li> are primarily developed elsewhere, or - <li> require patches to Octave, or - <li> are designed for older versions of Octave, or - <li> haven't been tested enough. -</ul></li> - <li> <b><tt>main/</tt></b><br/> - Packages which may eventually be included in the main octave - distribution. As such, they should follow Octave conventions. - The octave-forge CVS tree should be the primary development/release - site. All functions should work with the latest Octave - interpreter without any special compilation switches or patches - applied. -</li> - <li> <b><tt>nonfree/</tt></b><br/> - Packages which are not freely modifiable and redistributable - with modifications, or which depend on code which is not - free. This includes functions which only permit non-commercial - use and functions which must be kept together as a package. - Functions in all other directories must be freely redistributable - with modifications. Functions in non-free must be freely - redistributable for non-commercial use. Functions of unknown - license should not be included anywhere, since no license implies - default license implies no rights to redistribute. -</li> - <li> <b><tt>packages/</tt></b><br/> - This is the target directory, where the source packages are placed. It - is also the directory where the test code is run for each of the - packages and where the source RPMs are automatically built. There - should be no reason for the user to add files to this directory -</li> -</ul> - -<h3>Add a copyright notice</h3> -<p>Each file in octave-forge must contain a copyright notice. -If you wish to release your -code under the -GNU <a href="http://www.gnu.org/licenses/gpl.html">GPL</a> -, insert the following text at the top of your file:</p> -<pre> -## Copyright (C) <span style="color: #800000;"><i>year</i></span> <span style="color: #800000;"><i>Your Name</i></span> <<span style="color: #800000;"><i>your@preferred.email</i></span>> -## -## This program is free software; you can redistribute it and/or modify -## it under the terms of the GNU General Public License as published by -## the Free Software Foundation; either version 2 of the License, or -## (at your option) any later version. -## -## This program is distributed in the hope that it will be useful, -## but WITHOUT ANY WARRANTY; without even the implied warranty of -## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -## GNU General Public License for more details. -## -## You should have received a copy of the GNU General Public License -## along with this program; if not, write to the Free Software -## Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA -</pre> - -<p>Here are other popular open source licenses:</p> -<ul> - <li><a href="http://www.gnu.org/licenses/lgpl.html">GNU Lesser GPL</a></li> - <li><a href="http://www.gnu.org/licenses/fdl.html">GNU Free Documentation License</a></li> - <li><a href="http://www.opensource.org/licenses/artistic-license.html">Artistic License</a></li> - <li><a href="http://www.opensource.org/licenses/bsd-license.html">BSD License</a></li> -</ul> -<p>Consult -<a href="http://www.opensource.org/licenses/index.html">opensource.org</a>. -for a comprehensive list of Open Source licenses.</p> - -<h3>Package structure</h3> -<p> -Octave has evolved into a source repository is octave pacakges rather -than a package in itself. Each sub-directory is considered to be a -package and should respect Octave's package managers file layout.</p> -<dl> -<dt>package/NOINSTALL -<dd> This is an optional file, whose presence tells octave-forge - that this package should be ignored. This is typically for - packages that are kept for historical reasons. -<dt>package/DESCRIPTION -<dd> This is a required file containing information about the - package. It must contain the following fields - <table border="1"> - <tr><td>Name:</td> - <td>Name of the package</td></tr> - <tr><td>Version:</td> - <td>Version of the package</td></tr> - <tr><td>Date:</td> - - <td>Date of last update</td></tr> - <tr><td>Author:</td> - <td>Original author of the package</td></tr> - <tr><td>Maintainer:</td> - <td>Maintainer of the package</td></tr> - <tr><td>Title:</td> - - <td>A one line description of the package</td></tr> - <tr><td>Description:</td> - <td>A one paragraph description of the package</td></tr> - <tr><td>Categories:</td> - <td>Optional keyword describing the package - (if no INDEX file is given this is mandatory)</td></tr> - <tr><td>Problems:</td> - - <td>Optional list of known problems</td></tr> - <tr><td>Url:</td> - <td>Optional list of homepages related to the package</td></tr> - <tr><td>Depends:</td> - <td>A list of other octave packages that this package - depends on. This can include dependencies on particular - versions, which a format. -<pre> - Depends: package (>= 1.0.0) -</pre> - Possible operators are <, <=, ==, >= or >. If the part - of the dependency in () is missing, any version of the - package is acceptable. Multiple dependencies can be - defined either as a comma separated list or on separate - Depends lines.</td></tr> - <tr><td>License:</td> - <td>An optional short description of the used license - (e.g. GPL version 2 or newer). This is optional - since the file COPYING is mandatory.</td></tr> - <tr><td>SystemRequirements:</td> - <td>These are the external install dependencies of the package - and are not checked by the package manager. This is here as a - hint to the distribution packager. They follows the same - conventions as the Depends keyword.</td></tr> - <tr><td>BuildRequires:</td> - <td>These are the external build dependencies of the package - and are not checked by the package manager. This is here as - a hint to the distribution packager. They follows the same - conventions as the Depends keyword. Note that in - general, packaging systems such as rpm or deb and - autoprobe the install dependencies from the build - dependencies, and therefore the often a BuildRequires - dependency removes the need for a SystemRequirements - dependency.</td></tr> - </table> - The file format should be something like this: - </p> - <ul> - <li>Lines starting with # are comments</li> - - <li>Lines starting with a blank character are continuations - from the previous line.</li> - <li>Everything else is of the form NameOfOption: ValueOfOption</li> - </ul> - The developer is free to add additional arguments to the - DESCRIPTION file for their own purposes. Note that - octave-forge contains an automatic build process of RPMs and - DEBs from the octave packages, and this relies on the - DESCRIPTION files being correctly formatted. One further - detail to aid the packager is that the SystemRequirments and - BuildRequires keywords can have distribution dependent - section, and the automatic build process will use these. An - example of the format of this is -<pre> - BuildRequires: libtermcap-devel [Mandriva] libtermcap2-devel -</pre> - where the first package name will be used as a default and if - the RPMs are built on a Mandriva distribution, then the second - package name will be used instead. -<dt>package/COPYING -<dd> This is a required file containing the license of the package. -<dt>package/INDEX -<dd> This is an optional file describing the functions provided by - the package. If this file is not given then one with be - created automatically from the functions in the package and - the Categories keyword. -<dt>package/PKG_ADD -<dd> An optional file that includes commands that are run when the - package is added to the users path. Note that PKG_ADD - directives in the source code of the package will also be - added to this file by the octave package manager. Note that - symbolic links are to be avoided in packages, as symbolic - links do not exist on some file systems, and so a typical use - for this file is the replacement of the symbolic link -<pre><i> -ln -s foo.oct bar.oct -</i></pre> - with an autoload directive like -<pre><i> -autoload ('bar', which ('foo')); -</i></pre> -<dt>package/PKG_DEL -<dd> An optional file that includes commands that are run when the - package is removed from the users path. Note that PKG_DEL - directives in the source code of the package will also be - added to this file by the octave package manager. -<dt>package/Makefile -<dd> This is an optional file that is for the use of Octave-Forge - only. It allows the developer to have fine control over - exactly what is included in the package and anything that - needs to be done before or after the package is built. The - default Makefile is -<pre> -<i> -include ../../Makeconf -include ../../pkg.mk - -PKG_FILES = COPYING DESCRIPTION $(wildcard INDEX) $(wildcard PKG_ADD) \ - $(wildcard PKG_DEL) $(wildcard post_install.m) \ - $(wildcard pre_install.m) $(wildcard on_uninstall.m) \ - $(wildcard inst/*) $(wildcard src/*) $(wildcard doc/*) \ - $(wildcard bin/*) - -pre-pkg/%:: - # Do nothing prior to packaging - -post-pkg/%:: - # Do nothing post packaging -</i> -</pre> - which packages all of the required and existing optional files - and directories discussed here. -<dt>package/pre_install.m -<dd> This is an optional script that is run prior to the - installation of a package. -<dt>package/post_install.m -<dd> This is an optional script that is run after the - installation of a package. -<dt>package/on_uninstall.m -<dd> This is an optional script that is run prior to the - de-installation of a package. -<dt>package/doc -<dd> An optional directory containing documentation for the - package. The files in this directory will be directly - installed in a sub-directory of the installed package for - future reference. Note that any html files included in this - directory will be included in the octave-forge package - webpages. To include images or arbitrary files use a - sub-directory html/ in this directory. -<dt>package/inst -<dd> An optional directory containing any files that are directly - installed by package. Typically this will include any m-files. -<dt>package/bin -<dd> An optional directory containing files that will be added to - the Octave EXEC_PATH when the package is loaded. This might - contain external scripts, etc, called by functions within the - package. -<dt>package/src -<dd> An optional directory containing code that must be 'built' prior - to the packages installation. If this directory contains a - file autogen.sh, and package/Makefile does not exist, this - script will be called prior to the packaging. The Octave - package manager will execute "./configure" in this directory - is this script exists, and will then call "make" if a file - "Makefile" exists in this directory. "make install" will - however not be called. If a file called "files" exist all - files listed there will be copied to the "inst" directory, so - they also will be installed. If the "src/files" file doesn't - exist "src/*.m" and "src/*.oct" will be copied to - "inst". There are two reasons for doing this rather than "make - install": - <ul> - <li>At some point, it would be good to have a 'build' command - that creates a binary version of a package. I don't mean a .dep - or a .rpm, but an octave package, in which everything has been - compiled. - <li>At some point in the future, somebody clever might tell us - that the package system should run in a sandboxed environment - for security reasons. - </ul> -</dl> - -<h3>Submit your code!</h3> -<p>You are now ready to upload your code to the Gnu Octave Repository. -Do this with two CVS commands--one to add a new -entry for your file in the octave-forge catalog, and a second command -to actually upload the file:</p> -<pre> - $ cvs add <span style="color: #800000;"><i>files</i></span> - $ cvs commit <span style="color: #800000;"><i>files</i></span> -</pre> -<p>After hitting the carriage return at the end of the commit command, -CVS will open your default editor so that you can enter comments about -the commit. The first time you commit a file the comment might be -something as simple as `Initial commit into CVS.' However, for all -subsequent commits please add meaningful comments that explain why -changes were made to the file since all comments will appear in the -changelog. Try to gather related changes into one commit command.</p> - -<p>Aside: the default editor can be defined like so:</p> -<pre> - $ export EDITOR=<span style="color: #800000;">vim</span> -</pre> - -<p>If you are uploading an entire package, then put your directory into the -octave-forge tree and do the following:</p> -<pre> - $ cd octave-forge/main - $ cvs add <span style="color: #800000;"><i>package</i></span> - $ cvs commit <span style="color: #800000;"><i>package</i></span> - $ cd <span style="color: #800000;"><i>package</i></span> - $ cvs add * - $ cvs commit * -</pre> - -<p>You may find it easier to use the import command, especially if your -package contains subdirectories. In this case, you should not put -your directory into the octave-forge tree. Instead, change to the -root of your package tree and enter the following:</p> -<pre> - $ cd <span style="color: #800000;"><i>package</i></span> - $ cvs -d:ext:<span style="color: #800000;"><i>sflogin</i></span>@octave.cvs.sourceforge.net:/cvsroot/octave import \ - -m "<span style="color: #800000;"><i>package name</i></span>" octave-forge/<span style="color: #800000;"><i>main/package</i></span> <span style="color: #800000;"><i>sflogin</i></span> start -</pre> - -<p>You can then fetch the new package from octave-forge as follows:</p> -<pre> - $ cd octave-forge - $ cvs -q update -d -</pre> - -<p>From time to time, you will need to synchronize with CVS:</p> -<pre> - $ cd octave-forge - $ cvs -q update -d -</pre> -<p>Each file will be listed with one of the following codes:</p> -<ul> -<li> `?' for files you created didn't add and commit.</li> -<li> `M' for files you modified but didn't commit.</li> -<li> `C' for files which have unresolvable conflicts. Look inside the file to -see what it was that couldn't be resolved. It will be clearly marked, or you -can do a cvs diff on the file to highlight the conflict.</li> -<li> `U' for files you haven't touched but are modified on the server.</li> -<li> `P' for files you have modified in a way consistent with the modifications -on the server (?), e.g., because you submitted a patch for someone else to apply.</li> -</ul> - -<h3>Learn more about CVS</h3> -<p>The few CVS commands shown here just scratch the surface of this -powerful versioning package. If you become an active contributor -you will benefit from learning more CVS commands and understanding -how CVS works. -The -<a href="http://cvsbook.red-bean.com/cvsbook.html"> -CVS Book</a> is a great place to begin your exploration.</p> - -<h3>Join the developers' mailing list</h3> -<p>Finally, consider joining the octave-forge developer's -<a href="http://lists.sourceforge.net/lists/listinfo/octave-dev"> -mailing list</a>. It is very low traffic. It is used to announce -pending releases of octave-forge and discuss issues related to -working with octave-forge. Discussion of the functions in -octave-forge mostly occurs on the primary octave mailing lists.</p> - -__TRAILER__