Follow these simple steps to upload a new toolbox directory (MatLinks administrators only):

• If you have trouble with the following instructions, check the SourceForge documentation.
• First also make sure you're authorised for access. If you haven't yet contacted MatLinks to express interest in contributing to the project, please email us. If you're already an active contributor, you need to become a SourceForge member, and then email your userid to MatLinks to become authorised for administrative access.
• If you're using Windows, you may find it easiest to skip all the steps below and shoot straight for the SourceForge Setup utility.

Linux/UNIX contributors:

1. If you don't have a CVS client (concurrent versions system), download and compile one.
2. If you don't have an SSH/SCP client (secure socket handler/secure copy protocol), download and compile them.
3. If you don't have TCL/Tk (tool command language/toolkit), download and compile it.
4. If you don't have GNU diff (file differencing), download and compile GNU difftools.

DOS/Windows contributors:

1. Install the CVS client (concurrent versions system):
• download CVS for DOS
• download CVS for Windows
2. Install an SSH/SCP port (secure socket handler/secure copy protocol).
   • download SSH/SCP for DOS
3. Install the TCL/Tk (tool command language/toolkit).
   • download TCL/Tk for DOS
4. Install a diff application of your choice:
   • If you're a DOS user, download the GNU diff DOS port
   • If you're a Windows user, select any of several packages
5. Download and run the setup batch file from the DOS prompt or Start->Run... menu option.
6. Reboot your machine.

...If you installed WinCVS, here's how to set it up for MatLinks:

1. In Admin->Preferences..., under the General tab, set CVSROOT to username@cvs.matlinks.sourceforge.net:/cvsroot/matlinks
2. Make sure you're using the "standard" CVS version.
3. Under the Ports tab, specify an alternate rsh name: ssh.
4. Under the WinCVS tab, you may specify your favourite text editor and also the "diff" application you ultimately decided upon.
5. Under the same tab you should set your "HOME" directory to C:\HOME.
6. If WinCVS says TCL is not available even though you downloaded and installed it, you must add the TCL/Tk installation directory to the PATH specification in autoexec.bat and re-boot before you can type interactive shell commands in the WinCVS shell window at the bottom.

«!» Before proceeding... please note that what you will be uploading is a mirror of your local toolbox development directory. MatLinks requires that you adhere to a common development directory structure, to facilitate concurrent development efforts.

The Matlab-compatible toolbox path is:

toolchest/matlab_ver/copyleft/gpl/yourtoolbox

...where ver is the Matlab version your toolbox works under (for example, 4.2 or 5.3r11); and yourtoolbox is the name of your toolbox (all lowercase).

The GNU Octave-compatible toolbox path is:

chorus/octave_ver/toolbox/yourtoolbox

...where ver is the GNU Octave version your toolbox works under (for example, 2.0.16); and yourtoolbox is the name of your toolbox (all lowercase).

Please take a moment to browse the MatLinks CVS directory before you upload.

To upload your toolbox using CVS in DOS/Linux/UNIX:

1. Open a command-line window (xterm or MS-DOS prompt).
2. Login to the SourceForge CVS server:

   cvs -d:pserver:userid@cvs.matlinks.sourceforge.net:/cvsroot/matlinks login

   ...where userid is your SourceForge user ID.

3. cd to your toolbox path.
4. Upload your toolbox to the central CVS repository:

   cvs -duserid@cvs.matlinks.sourceforge.net:/cvsroot/matlinks import yourtoolbox

   ...where yourtoolbox is your toolbox name (all lowercase).

5. Logout from the SourceForge CVS server:

   cvs -d:pserver:userid@cvs.matlinks.sourceforge.net:/cvsroot/matlinks logout

   ...where userid is your SourceForge user ID.

To upload your toolbox using WinCVS in Windows:

1. In Admin->Preferences...->General->Authentication, select "passwd" file on the CVS server.
2. Click Admin->Login... and enter your SourceForge password.
3. In Admin->Preferences...->General->Authentication, select SSH server (leave RSA identity unchecked).
4. Using the Explorer interface at the left of WinCVS, locate your toolbox directory and double-click to open it. Then select this directory using Create->Import module... or ->Import from selection
5. Your toolbox directory will be scanned for standard file extensions. Check the dialogue report to verify that text/binary file translations are interpreted correctly by the filtering mechanism.
6. For the Module name and path, type in your toolbox path.
7. For the Vendor name, enter your SourceForge userid. The Release name is optional. You can also enter an optional note into the release logs.
8. Click [OK] and find the SSH DOS window (press Alt+Tab until you find it). SSH will prompt you for your SourceForge password. You must keep the SSH window active during your session, but you can minimise it if you want, since it will not ever display anything beyond the initial login prompt.
9. Your toolbox will start uploading. The status bar will display the upload progress. Depending on your toolbox size and connection speed, this can take a while!
10. When you're finished, in Admin->Preferences...->General->Authentication, select "passwd" file on the CVS server, and click Admin->Logout to log out of the SourceForge CVS server.

Using CVS, you can check out not only your own toolbox, but those of any other MatLinks developers. In this way, we are all able to contribute to each others' work while maintaining the code integrity. All CVS code is presently development code.

To check out a toolbox using CVS in DOS/Linux/UNIX:

1. Open a command-line window (xterm or MS-DOS prompt).
2. Login to the SourceForge CVS server:

   cvs -d:pserver:userid@cvs.matlinks.sourceforge.net:/cvsroot/matlinks login

   ...where userid is your SourceForge user ID.

3. cd to the toolbox path.
4. Check out your toolbox to the central CVS repository:

   cvs -duserid@cvs.matlinks.sourceforge.net:/cvsroot/matlinks co toolboxpath

   ...where toolboxpath is the toolbox you want to modify (all lowercase).

5. Logout from the SourceForge CVS server:

   cvs -d:pserver:userid@cvs.matlinks.sourceforge.net:/cvsroot/matlinks logout

   ...where userid is your SourceForge user ID.

To check out a toolbox using WinCVS in Windows:

1. In Admin->Preferences...->General->Authentication, select "passwd" file on the CVS server.
2. Click Admin->Login... and simply press [Enter] when prompted for a password.
3. Using the Explorer interface at the left of WinCVS, locate the toolbox directory and double-click to open it.
4. Then click Create->Checkout Folder... and your toolbox will be checked out. The status bar will display the checkout progress. Depending on your toolbox size and connection speed, this can take a while!
5. When you're finished, select Admin->Logout to log out of the SourceForge CVS server

Once you've checked out the toolbox you can edit files locally and then update the CVS copy.

To update a toolbox using CVS in DOS/Linux/UNIX:

1. cd to the toolbox path.
2. Update the SourceForge CVS server:

   cvs update

3. To commit the changes:

   cvs commit -m "comments"

   ...where comments are any comments you wish to place into the update log.

To update using WinCVS in Windows:

1. Using the Explorer interface at the left of WinCVS, locate the toolbox directory and double-click to open it.
2. Then click Modify->Update Selection... and the selected file(s) will be synchronised in CVS.
3. To commit the changes, click Modify->Commit Selection... and enter any comments you wish to place into the update log.

You can also add files to, or delete files from, the CVS repository (MatLinks administrators only).

To add/delete a file using CVS in DOS/Linux/UNIX:

1. cd to the toolbox path.
2. To add one or more files:

   cvs add files

3. To add one or more files:

   cvs remove files

   ...where files are what you wish to add or delete within the current CVS toolbox.

To add/delete a file using WinCVS in Windows:

1. Using the Explorer interface at the left of WinCVS, locate and highlight the file(s).
2. Then click Modify->Add Selection... or Modify->Remove Selection...

When you're ready to release another version of your toolbox, you should upload it to the MatLinks release website via FTP. Please do not confuse release versions with ongoing work. Ongoing development work should continue using the CVS version until you want to freeze changes in your current source code.

Initial releases should be alpha versions (with a letter "a" revision suffix). At this point you should stop adding new code, and branch off a new CVS alpha copy for the source so that ongoing development work does not mangle your alpha release. Alpha versions will not be advertised on the MatLinks.net website, but they will be available on matlinks.sourceforge.net when you release them.

After you are comfortable with any changes made during the alpha test phase, you can re-release the alpha toolbox as a beta version (with a letter "b" revision suffix). At this stage you should also check that you've updated your release versions in the readme files, deleted old files (del #* *~), and that your email and contact information is correct. Beta versions will be advertised on the MatLinks.net website, and so should be as bug-free as possible before coming under public scrutiny.

Once outstanding beta bugs are fixed, you can release a stable version. While the stable version may have bugs, these should be applied to the development source only. Once a stable version is released, it must remain frozen. You can publish a known-bugs list to acknowledge known issues that will be resolved in forthcoming releases.

Note that the MatLinks CVS subdirectory yourtoolbox (where yourtoolbox is the name of your MatLinks toolbox) always hosts the active development version of your work. There are no exceptions to this rule!

1. The alpha CVS branch should go into a subdirectory name yourtoolbox-alpha.
2. To create the beta CVS version, simply rename subdirectory yourtoolbox-alpha to yourtoolbox-beta. Do not branch off yet another version. If you want to save your alpha version then archive your local copy before you rename the CVS directory.
3. To create the release version, checkout the yourtoolbox-beta toolbox to your local drive and make an immediate back-up of the new release snapshot for safe-keeping.
4. Generate the zip file(s) and/or tarball(s) for the release.
5. Upload the release files to the MatLinks FTP site.
6. Log into SourceForge.net and release the new version.
7. Verify that you can download and install the release version yourself.
8. Remove the yourtoolbox-beta toolbox directory from the CVS repository

The SourceForge CVS server automatically backs up a snapshot of the MatLinks CVS repository on a nightly basis. To download the latest MatLinks snapshot tarball for yourself, click here.

The concurrent versions system is very popular and used extensively in the UNIX world. You can find documentation very easily by searching the web. Try the mirror at this website, and also try the SourceForge documentation.

To upload a new release:

1. Anonymous FTP to download.sourceforge.net.
2. For the password use your SourceForge email address

userid@users.sourceforge.net

...where userid is your SourceForge userid.

3. cd incoming to get to the anonymous FTP upload directory.
4. (m)put your release file(s)/archive(s) using binary FTP transfer .
5. Log into SourceForge.net.
6. Submit your toolbox release file(s) at the MatLinks release area.

«!» Please note...

• You have a limited time to submit your release before the SourceForge FTP server erases your toolbox.
• Do not post any files other than your own release as this will interfere with other developers trying to upload their own work.
• Do not generate a new module for your release as this will interfere with the MatLinks release structure.

There's also some supporting documentation from SourceForge.

MatLinks maintains a general FTP site at SourceForge which is very useful for sharing files that are not official MatLinks download files.

To upload a non-release file for public access:

1. SCP your file(s) to matlinks.sourceforge.net as if you are submitting a new toolbox for evaluation (all on one line):

scp -v -pw password yourfile(s) userid@shell.sourceforge.net:/home/groups/ftp/pub/matlinks

...where userid and password are your SourceForge username and password, and yourfile(s) is the filename or list of filenames you wish to share on the FTP site. (For DOS/Windows, type pscp instead of scp.) You can optionally omit the -pw password option, if you'd prefer to type it in manually after logging in.

2. Now you should see your release file(s) on the MatLinks FTP site.

«!» Please...

• Send an email to MatLinks letting us know what you've uploaded and for what purpose, or we may accidentally erase your file(s) if we don't recognise them.

It's often crucial to track and fix bugs as soon as they appear. First, check that someone else hasn't already fixed the bug you found. It's a good idea anyway to keep your code patched with the latest fixes.

It's easy to make your own patch to fix a bug in the MatLinks archives.

• If you use DOS/Windows, download diff.exe and patch.exe and update your PATH to find them.
• Next open a command-line window (xterm or MS-DOS prompt)

To patch a bug and submit the patch to MatLinks:

1. Fix the bug(s) you found in the m-file filename.m.
2. Make sure the new version works as you expect.
3. Save the fixed/tested version of filename.m as filename.new.
4. Type

diff -b -B -w filename.m filename.new > filename.fix

...where filename.m is the original distribution file, filename.new is your debugged copy, and filename.fix is the patch file you want to create.

5. Upload filename.fix to the MatLinks bug patch area or email it to bugs@matlinks.net with a description of the bug and your fix.

To test your patch or apply a patch from someone else at MatLinks:

1. Download the patch(es) from the MatLinks bug patch area.
2. cd to the directory with the m-file to be patched.
3. Type

   patch -p0 filename.m < filename.fix

   ...where filename.m is the original distribution file with the bug(s), and filename.fix is the patch file you downloaded from MatLinks.

4. Once you've applied the patch, check for any .rej files (rejects). If you have these, you might try applying your patch with a different level of "fuzziness" by using patch -p1 or patch -p2. If you still get reject files, you should edit the m-file manually. The lines that need replacing are listed in the patch file: lines prefixed with "<" should generally be replaced by the subsequent lines prefixed with ">".
5. If you find a bug or problem in a patch file submission please notify us.
6. If you followed the above steps to test your own patch submission, you should now compare the files to make sure they're identical:

   diff -b -B -w filename.m filename.new

   ...where filename.m is the patched distribution file, and filename.new is your debugged copy.

7. The result should be that no output is produced, meaning the files are in fact identical. Otherwise, there's a problem with the patch file. Please don't leave buggy patch files at the MatLinks patch area! =)