Contributing Code to the GNU Octave Repository
To contribute your .m files, C++, C, or Fortran code to the GNU Octave Repository (octave-forge) you need to
- have an account on SourceForge,
- be registered as an Octave Forge developer,
- have svn and ssh, installed on the computer from which you will submit contributions.
The first two requirements are easy. If you don't already have one, create a SourceForge account here. To register as an Octave Forge developer, subscribe to the Octave maintainers mailing list and send a request including your SourceForge username. Include a bit of information about the code you plan to submit and also a first code contribution under the form of a patch. Use
$ svn diffto create this patch if you are using the SVN tree, or just
$ diff -u original_file.m updated_file.mwith a local of the original function if you aren't. Finally, if your computer runs linux or FreeBSD, chances are good that both ssh and subversion are already installed on your system. If they aren't, you will need to find prebuilt packages for them or download their source code and build them.
Download the latest octave-forge distribution
It is expected that 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 SVN checkout command:
$ cd working_directory $ svn checkout http://svn.code.sf.net/p/octave/code/trunk/octave-forge/
Where does your code belong?
Put your file(s) in a subdirectory under the octave-forge/ directory. Here are some guidelines to help you decide where your code belongs:
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.
Documentation for octave in general. Documentation for specific packages goes into the doc/ subdirectory of the individual package directories. This directory also contains the automatically built html code for the website.
- are too narrow in scope for main/, or
- act as alternatives for functions in main/, or
- do not follow octave conventions (because they want to retain compatibility with matlab for example), or
- are primarily developed elsewhere, or
- require patches to Octave, or
- are designed for older versions of Octave, or
- haven't been tested enough.
Packages that supply translations of core Octave functions and Octave-Forge packages. The directory base/template/ contains example code to and the directory base/help the original text of the functions to translate.
Packages which may eventually be included in the main octave distribution. As such, they should follow Octave conventions. The octave-forge SVN 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.
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
Add a copyright notice
Each file in octave-forge must contain a copyright notice. If you wish to release your code under the GNU GPL , insert the following text at the top of your file:
## Copyright (C) year Your Name <email@example.com> ## ## 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 3 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, see <http://www.gnu.org/licenses/>.
Here are other popular open source licenses:
Consult opensource.org. for a comprehensive list of Open Source licenses.
Octave Forge has evolved into a source repository of Octave packages rather than a package in itself. Each sub-directory is considered to be a package and should respect Octave's package managers file layout.
- 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.
- This is a required file containing information about the
package. It must contain the following fields
Name: Name of the package Version: Version of the package Date: Date of last update Author: Original author of the package Maintainer: Maintainer of the package Title: A one line description of the package Description: A one paragraph description of the package Categories: Optional keyword describing the package (if no INDEX file is given this is mandatory) Problems: Optional list of known problems Url: Optional list of homepages related to the package Autoload: Optional field that sets the default loading behavior for the package. If set to 'yes', 'true' or 'on', then Octave will automatically load the package when starting. Otherwise the package must be manually loaded with the pkg load command. This default behavior can be overridden when the package is installed. Depends: A list of other octave packages that this package depends on. This can include dependencies on particular versions, with a format.
Depends: package (>= 1.0.0)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.
License: An optional short description of the used license (e.g. GPL version 2 or newer). This is optional since the file COPYING is mandatory. SystemRequirements: 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. BuildRequires: 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 SVNRelease: This is an optional field intended to help the developer remember the SVN release number from which the package was produced, it will in genaral not be seen by the package users.
The file format should be something like this:
- Lines starting with # are comments
- Lines starting with a blank character are continuations from the previous line.
- Everything else is of the form NameOfOption: ValueOfOption
BuildRequires: libtermcap-devel [Mandriva] libtermcap2-develwhere 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.
- This is a required file containing the license of the package.
- 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.
- 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
ln -s foo.oct bar.octwith an autoload directive like
autoload ('bar', which ('foo'));
- 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.
- 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
include ../../Makeconf 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 packagingwhich packages all of the required and existing optional files and directories discussed here.
- This is an optional script that is run prior to the installation of a package.
- This is an optional script that is run after the installation of a package.
- This is an optional script that is run prior to the de-installation of a package.
- 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.
- An optional directory containing any files that are directly installed by package. Typically this will include any m-files.
- 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.
- 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
- 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.
- At some point in the future, somebody clever might tell us that the package system should run in a sandboxed environment for security reasons.
Submit your code!
You are now ready to upload your code to the GNU Octave Repository. Do this with two SVN commands--one to add a new entry for your file in the octave-forge catalog, and a second command to actually upload the file:
$ svn add files $ svn commit files
The first time you run the above during a session, you will be requested to type your octave-forge username and password.
After hitting the carriage return at the end of the commit command, SVN 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 SVN.' 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.
Aside: the default editor can be defined like so:
$ export EDITOR=vim
If you are uploading an entire package, then put your directory into the octave-forge tree and do the following:
$ cd octave-forge/main $ svn add package $ svn commit package $ cd package $ svn add * $ svn commit *
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:
$ cd path/below/package $ svn import package \ https://svn.code.sf.net/p/octave/code/trunk/octave-forge/main/package
You can then fetch the new package from octave-forge as follows:
$ cd octave-forge $ svn status -u
From time to time, you will need to synchronize with SVN:
$ cd octave-forge $ svn status -u
Each file will be listed with one of the following codes:
- `?' for files you created didn't add and commit.
- `M' for files you modified but didn't commit.
- `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 svn diff on the file to highlight the conflict.
- `U' for files you haven't touched but are modified on the server.
- `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.
Make a release of your package and publish its function reference
When you are ready to make a new release of your package you will have to update the website to show the package newly released as follows:
- bump the `Version' number (and optionally the `SVNRelease') in the package DESCRIPTION file
produce a tar.gz of the package, take note of its md5 checksum and encode it with uuencode
$ cd $ cd octave-forge/extra/ $ svn export package ~/package Export complete. $ cd $ grep -i version package/DESCRIPTION Version: version License: GPL version 2 or later $ tar czf package-version.tar.gz package/ $ ls *.tar.gz package-version.tar.gz $ md5sum package.tar.gz
generate the function reference HTML files with the command
generate_package_htmlfrom the package `generate_html':
$ octave -q --eval "pkg install package-version.tar.gz \ pkg load generate_html; generate_package_html ('package', 'package-html', 'octave-forge')" $ ls package-html/ packageproduce a tarball, take note of its checksum and encode it with uuencode
$ tar cvzf package-html.tar.gz package-html $ md5sum package-html.tar.gz
- Post the package, html docs and md5 checksums to the package release tracker asking for review and upload it on the server. Once its accepted, an Octave Forge admin will upload and make the announcement on the mailing list.
Learn more about SVN
The few SVN commands shown here just scratch the surface of this powerful versioning package. If you become an active contributor you will benefit from learning more SVN commands and understanding how SVN works. The SVN Book is a great place to begin your exploration.
Join the developers' mailing list
Finally, consider joining Octave's maintainers mailing list. It is very low traffic. It is used to discuss development issues related to both Octave and Octave Forge.