wxCode Maintainer Guide

NOTE: this document applies only to the wxCode maintainers.

Index of the page:


STEP #1: set up the CVS for your component

^ TOP

Note: since some developers prefer to use Subversion instead of CVS, some wxCode components are hosted in the CVS repository, other in the Subversion repository.
So, you need to setup Subversion only if your component is there or if it uses components placed in the Subversion repository or if you want to get all wxCode components on your hard disk.

› For Unix-based OS:

You will need to have cvs installed and set up on your system. You will also need a SSH client such as OpenSSH installed and set up. A modern linux distribution will already have both. Finally you will need a sourceforge username (here referenced as mysfname) and a password.

Here is a small tutorial which will guide you in the process. Open a shell (e.g. Konsole or gnome-terminal) and copy and paste (comments won't harm) the following commands:

        cd                   # this brings to the home
        export CVS_RSH=ssh   # this tells cvs to communicate using ssh
        cvs -d:ext:mysfname@wxcode.cvs.sourceforge.net:/cvsroot/wxcode co wxCode

        # now you will be asked for your password: give the password of your SourceForge account.
        # Then all of the wxCode modules will be downloaded, 58 MB at May 2006
        # (aren't you glad you have broadband?).
    

Now you have the ~/wxCode/components/YOURCOMPONENT folder; it should contain a standard tree like the one of the "wxCode\template" directory. Copy into it the files that comprise your module and change/remove existing files to suit your needs. Tell cvs about your project files with a command like:

        cvs add myfile.1 myfile.2          # tell CVS about new files
        cvs commit -m "Initial commit"     # commit them to the repository
    

The bit in quotes is used by cvs as a label for your future reference. You can substitute a message of your choice, or "" for none. If you omit the -m "something" then your default editor will be summoned so that you can compose the message there. After a delay while the sourceforge server gets updated, all should be well.

Notice that the initial checkout required the long form of command with -d:ext:mysfname@wxcode.cvs.sourceforge.net:/cvsroot/wxcode. Afterwards this is unnecessary as it is stored in your local cvs, so as long as you are in a directory below /home/me/wxCode, you won't need to use that option. Your password is not remembered though, so you will be asked for it with each command.


› For Windows-based OS:

Upgrade your system to linux, then proceed as above ;-)
If you're really decided to use Windows, then you need to download a CVS client like TortoiseCVS or WinCVS... then set the following data in your client:

Protocol: Extended shell (:ext) *
Server: wxcode.cvs.sourceforge.net
Repository folder: /cvsroot/wxcode
User name: yourSFusername
Module: wxCode

* if you have problems with ext try to use "Secure shell SSH (:ssh:)"

Please note that all CVS commands are case-sensitive and thus you should check carefully the strings typed in order to avoid problems. The CVSROOT shown by your client at the end should be:

:ssh:yourSFusername@wxcode.cvs.sourceforge.net:/cvsroot/wxcode

Then, just choose in your CVS client the "checkout" command and wait...


› For both Linux-based and Windows-based OS:

Note that the entire wxCode CVS repository is quite large (about 40 MB at July 2005) and that you can also download only what you need. This is done by checking-out only the modules:

        wxCode/build
        wxCode/template
        wxCode/components/YOURCOMPONENT

Otherwise, you can also download the wxCode CVS repository using SourceForge.net File Release System which is much much more fast than checking-out using CVS but also has some disadvantages:

  • It's not up-to-date as the CVS is, since wxCode CVS is continuosly modified and you should then do in any case a CVS update (which is however, quicker than a CVS checkout)
  • It requires to use the "changeroot.sh" script on the wxCode CVS repository downloaded to use it in write mode.

If you find problems with this download, please ask in the wxCode-users mailing list.

Both for linux and windows users, there is much more detail available on sourceforge at SourceForge CVS documentation page, and in the online CVS book.

After the complete download of the wxCode repository, you're ready for step #2...


STEP #2: set up the SVN for your component

^ TOP

Note: you need to setup Subversion only if your component is there or if it uses components placed in the Subversion repository.

› For Unix-based OS:

You will need to have subversion installed and set up on your system. You will need a sourceforge username (here referenced as mysfname) and a password (these will be asked only for write operations).

Open a shell (e.g. Konsole or gnome-terminal) and copy and paste (comments won't harm) the following commands:

        cd                   # this brings to the home

        # this command will now checkout all wxCode components of the SVN repository
        # in a directory called 'wxCode'
        svn co https://svn.code.sf.net/p/wxcode/code/trunk/wxCode
    

Now you have the ~/wxCode/components/YOURCOMPONENT folder; it should contain a standard tree like the one of the "wxCode\template" directory. Copy into it the files that comprise your module and change/remove existing files to suit your needs. Tell subversion about your project files with a command like:

        svn add myfile.1 myfile.2          # tell SVN about new files
        svn commit -m "Initial commit"     # commit them to the repository
    

The bit in quotes is used by subversion as a label for your future reference. You can substitute a message of your choice, or "" for none. If you omit the -m "something" then your default editor will be summoned so that you can compose the message there. After a delay while the sourceforge server gets updated, all should be well.


› For Windows-based OS:

You need to download a Subversion client like TortoiseSVN and just use as URL:

https://svn.code.sf.net/p/wxcode/code/trunk/wxCode

Adding files and committing are all operations extremely easy with the GUI of TortoiseSVN; refer to its manual for more info.


› How to merge wxCode CVS with wxCode SVN:

If you want to keep both wxCode CVS and wxCode SVN in a single wxCode folder on your hard disk, you just have to checkout the CVS and SVN repositories of wxCode (see above) in two different folders.
Then, move the components of the Subversion repository in the wxCode/components folder created by the CVS checkout (don't forget to move also the hidden .svn folders!).

Now you can use both CVS and SVN commands (or graphical CVS and SVN clients) in that folder.


STEP #3: upload your sources

^ TOP

This is the longest part, since it probably requires you to do some changes to your component and test them:

  1. look at the template page: it explains some basic rules about naming of the source and header files for your component, the website of your component, etc
  2. learn how to create a bakefile-based build system for your component; this enables you to support multiple compilers, multiple platforms and multiple build settings (ANSI/Unicode, DLL/static, debug/release, etc) with little effort; use the wxCode bakefile page and wxCode autoconf page as guide.
  3. add all the stuff regarding your component to the CVS/Subversion (except, as said in the readme, for the screenshots, the documentation and the release packages) and edit the "website" folder for your component...

STEP #4: make a release for your component

^ TOP

CVS is for wxCode maintainers; users just want to easily download an archive of the project. For this to be possible you need to make a file release through Sourceforge. Also remember that Open Source philosophy is "Release often, release early" !

› First ever file release of your project:

  1. Compress your files into one or more archives (tar.gz, tar.bz2 or zip); it's a good idea to name this something like myproject-1.0.ext (i.e. lowercase name, hyphen, version), with subsequent releases called 1.1 etc. You aren't allowed to use spaces in the name.
    Then, refer to the Sourceforge's FRS system help page for uploading it to Sourceforge servers (you can use various methods, choose your favourite one).
  2. Go to the Sourceforge page the wxCode file release page (Sourceforge will first get you to log on). Click "Edit releases" and look at the list of components available to be edited, you will (currently) see several entries called "USE THIS FOR NEW COMPONENTS", with a status of "Hidden". These are orphaned releases, unwanted and unloved. To adopt one, just click its "Edit This Release" link, delete any old files that were left behind, change the name and date to that of your project and set the status to "Active".
  3. Add or change whatever you wish in the first section (for wxCode projects you don't really need to fill in the Release Notes or Change Log). Now the important bit: you should see your uploaded archive(s) in section 2 (together with all the rest of the day's Sourceforge uploads). Tick the checkbox for your file(s), then click the "Add Files" button. Finally fill in the boxes in the newly-revealed Step 3, click Update/Refresh and you've made a File Release. To prove that it worked, go back to the wxCode webpage and check that you can download your archive successfully.

› Subsequent file releases:

The next time you want to make a file release for this project, the procedure is much the same. However when you go to the wxCode file release page, you click "Edit releases". On the next page, find your component and click its "Edit This Release" link. Then you upload the new archive as before.
It may be a good idea this time to write in the Release Notes box about what is new in this Release. It probably now makes sense to delete the old release, and change the release date.

More detailed information is available on this Sourceforge page.