Table of Contents
Fedora development can occur on any OS/Hardware combination that supports the required development tools. At the very least, this includes:
Recent Windows releases (NT4/2k, 95/98/Me, XP)
Modern Unix flavors (Linux, Solaris, etc.)
A JDK v1.4.2+, with any IDE you prefer. Note: In this guide, no particular IDE is assumed - instructions will be written assuming none.
CVS is used for revision control. It comes with most modern unix installations by default. For windows users, and those new to CVS, you can download and read about it at cvshome.org. From this point forward, this guide assumes your have the 'cvs' executable in your PATH, although your partciular IDE may already integrate CVS support. You may wish to consult the online cvs book as a reference.
SSH is used in conjunction with CVS to enable secure communication with the source code repository. Modern unix installations usually come with ssh(1) and ssh-keygen installed. Windows users can download an SSH client called Putty from this site. If you're a Windows user and you don't already have an SSH client and RSA key generator, go ahead and download (at least) putty, plink, pageant, and puttygen from that site. The remainder of this guide assumes that:
If you're a Unix user, you have ssh(1) and ssh-keygen installed and in your PATH.
If you're a Windows user, you have putty, plink, pageant, and puttygen installed and in your PATH.
Other tools necessary for building and unit testing of the project are included as part of the project within CVS in the res/ directory. They will be downloaded when you first perform a "checkout" operation from CVS. <<TODO: When source code is finally made public, some of these tools may need to be removed from CVS in order to comply with their licenses for redistribution. When that time comes, instructions will be included in this gude on what the tools are, how to get them, and where to put them so that the project builds and runs without problems. >>
To log into the project site at comm.nsdlib.org/projects/fedora, and to work with the CVS repository, you should have a SourceForge account.
Steps
OPTIONAL: Log into the project site (see the link in the upper-left on that page) using an SSL-capable browser to ensure that your account has been set up.
REQUIRED: Use ssh to log into comm.nsdlib.org to initialize your user directory.
This is necessary in order to use CVS.
Windows users: type plink comm.nsdlib.org Unix users: type ssh comm.nsdlib.org If it asks if you want to store the server's key in your cache, say yes. Then enter your username and password when prompted. When successful, you'll see a command-prompt. Type "exit" to logout. Your user directory should now be initialized.
SUGGESTED: Create a private/public RSA key pair if you don't already have one, and upload your public key to SourceForge.
This allows you to run CVS actions over the network without providing your password every time.
Windows users: type "puttygen", take the defaults, and click "Generate". Follow the instructions and then save your private and public keys in a secure place on your system.
Unix users: type "ssh-keygen" and you'll be led through the process. Make sure your public and private keys are saved in a place that ssh(1) will look (usually ~/.ssh, which is the default)
Note for both Windows and Unix users: using a passphrase on your private key isn't necessary if you keep your private key file secure (readable only by you). If you decide to use a key passphrase, make it anything you want, and note that whenever you use your private key, you'll need to manually provide that passphrase.
Now upload your public key to the SourceForge site by 1) logging in, then 2) selecting Account Maintenance , then 3) selecting Edit Keys from the bottom of that page where it says "CVS/SSH Shared Authorized Keys", then 4) pasting your public key into the box, and finally 5) selecting the Update button.
Windows users: type "pageant" to bring up the putty agent. This program keeps your private key in memory during secure network communication so that it can be used by the putty ssh client (plink). It runs in the background. Bring the pageant window to the foreground and select "add key", then select your private key file. You must do this each time you start pageant unless you automatically invoke pageant with the first parameter being the location of your private key. Note: this step is not necessary for Unix users because by default, ssh(1) looks in a standard place for your private key whenever it is invoked.
Test logging in without typing your password. Windows users: type plink username@comm.nsdlib.org (where username is your login name). Unix users: type ssh username@comm.nsdlib.org. Your ssh client should log you in automatically. Type exit to logout.
OPTIONAL: Set your CVSROOT environment variable to :ext:username@comm.nsdlib.org:/cvsroot/fedora, where username is your login name on the SourceForge site.
If you don't do this, you'll have to provide the -d option along with this information every time you do anything with cvs.
REQUIRED: Set your CVS_RSH environment variable to ssh (for Unix) or plink (for Windows)
This tells your cvs client that it can run cvs commands over your ssh client.
If you subscribe to the fedora-codewatch mailing list, you will get email notification of changes to the source of the project as they are checked into CVS. You may prefer not to recieve too many email messages, but still have an interest in code changes. In that case, don't subscribe (if you're already subscribed, unsubscribe) and periodically have a look at the mailing list archives.
When your system is properly configured as specified above, you can type: cvs co -P mellon, (the -P ignores deleted directories in the repository) and the project files from the repository will be copied to your system, in a directory named "mellon". This is your working copy. Note that cvs differs from other revision control systems in that checking out a file does not lock it for modification by other people.
The ant tool is included in the project files, under res/ant. You may already have ant installed on your system. If you don't, you will need to add <work_path>/mellon/res/ant/bin to your PATH environment variable before builds will work (where <work_path> is the full path to the directory in which you executed the "cvs co mellon" command above). If you're on a Windows system, use \ (backslash) instead of / (forward slash) in the PATH.
The CVS repository's copy of the project files is navigable from this page on the SourceForge site. When you commit changes to the CVS repository from your working copy, they will be reflected on the site.
A description of the cvs mellon/ directory structure follows.
The makefile for the entire project, in ant (v1.6) format. (Ant is a cross-platform build tool similar to make... Read more about it here, if you're interested.). This contains the dependencies and calls to external programs that help to produce the final form(s) of the project.
Components that 1) help in compiling the project to its final form(s), and 2) are necessary for the final form(s), but are not part of the intellectual basis of the project.
Components that help in compiling the project to its final form(s), but are neither 1) part of the intellectual basis of the project, nor 2) necessary for the final form(s) of the project.
Files and directories that are included with the final form(s) of the project, but are not 1) part of the intellectual basis of the project, nor 2) used during compilation of the project.
The intellectual basis of the project, organized into directories named by file type. There are many possible logical groupings of files within a project. The 'file type' grouping used at this directory level is the only one dictated outside the build.xml (ant) file. Groupings inside these directories are not necessary, but may be useful during compilation (for example, the java directory is organized by package because the java compiler expects it to be that way) Note that file type should usually be based on mime type distinctions, and if there is a standard file extension for the particular type, that should be used. For xml files that don't have a well-established extension, rather than putting them all in xml, put them in a directory using some obvious identifier for their schema namespace (but non-version specific, to be consistent with file extension conventions).
<<TODO: At the end of this list, insert other types, with brief descriptions and directory structure explanations, if applicable.>>
Java source code. See the javadocs for a description of the packaging scheme used (which also matches the directory scheme beneath src/java).
Be nice and document your code and make it readable by others. (Use consistent indenting, javadoc, etc.) Sun's Code conventions for Java provide a nice basis, but I don't think we have to be too anal about enforcing coding style -- shoot for consistency and clarity.
When committing changes, write a note (however short) indicating what you did.
Once a module checked into cvs is compiling, don't check in changes that cause builds to fail.
If you add a tool or library dependency to the project, 1) make sure it doesn't break supported platforms for development and deployment, and 2) check the tool into cvs in the appropriate place
If you modify the build.xml file, never introduce absolute paths, and never delete targets unless you're sure nobody is dependent on them.
To see the targets, be sure you're in the mellon directory, and type ant -projecthelp. To run a target, type ant <target_name>. After a main target is built, it should tell you where the result is.
<<TODO: As new targets come about (like the server target, and optimized variations of client and server), talk about them briefly here.>>
The client target (generated by typing "ant client") creates a client distribution in dist/client/. To run it after building it, cd to that directory and type java -jar client.jar.
CVS documentation can be daunting. Here's a quick guide to the most common tasks you'll use in CVS, biased to the Fedora development environment.
cvs co -P mellon
This example brings a copy of the entire mellon subtree (all project files) on to your system, creating the "mellon" directory (and sub-directories) if needed. You only need to do this once per working copy.
cvs update -d YourFile.java
You can also do this recursively on entire directories by specifying a directory instead of a file. The -d tells it to get newly created directories, which is usually what you want.
cvs ci -m "I changed that one part" YourFile.java
This example checks in a changed file, using a log message. If you want a multi-line log message, you can type this same command, but don't include the -m "message" part.
cvs add [-kb] MyFile.java
This example adds the file MyFile.java to the repository. Before a file is available to others for the first time, it must also be checked in.
cvs rm -f MyFile.java
The -f option tells CVS that before removing it from the repository, it should remove it from your working directory. If you don't specify -f, you must have already deleted the file from your working directory or this command will not run. Directories are deleted in the same way. Remove operations must be committed to take effect in the repository.
CVS allows for the concurrent modifications to working copies of files. This is not always a bad thing, but can create confusion and re-work headaches without adequate developer communication.
To remedy this, some people have written extensions to CVS that allow for strict locking (the default practice in most revision control systems), but these extensions are not available in our environment.
The other approach (which our environment supports) is to use a method called weak locking. Weak locking is supported by the cvs commands edit, unedit, watch, and watchers.
In weak locking, the repository provides several functions that aid in developer communication so we can see what people are working on.
cvs edit MyFile.java
Signals that you intend to edit this file. This creates what is called a "temporary watch" on the file, which signifies to other developers that you are working on the file. It also has the effect of "watch" until you "unedit" the file.
cvs unedit MyFile.java
Cancels the effect of a cvs "edit". This doesn't revert your changes -- it just signals to the repository that you are not an editor of this file. This is typically done after you have made changes and committed a file and are moving on to something else, or you've decided that you're no longer interested in changing the file.
cvs watch [add|remove]
Adds you to (or removes you from) the list of "watchers" for all actions on this file. If the repository is configured to do email notification (currently not the case), you will get an email any time someone does something with the file in the repository.
cvs watchers MyFile.java
Lists the people who are watching the file. This will include anyone who has a temporary watch, too (someone who is editing the file). It is a good idea to do this before editing a file to make sure nobody else is working on it at the same time. (Unless you've co-ordinated with someone to do concurrent mods on separate sections of the file, in which case CVS will do the merging for you at commit-time)
Here is the revision history of this guide:
$Log$
Revision 1.2 2006/01/26 19:55:52 eddie
minor corrections. this document actually needs a lot of edits
Revision 1.1 2005/01/27 05:12:36 eddie
moved all devdoc-related files to src/doc/devdocs,
edited buildfile accordingly
translated docbook to html and deleted the dbx files
Revision 1.10 2002/09/11 11:44:58 cwilper
updated as per bill's suggestion -- suggested key pair, and added
note on adding key pair to pageant.
Revision 1.9 2002/05/17 20:02:00 cwilper
Added section on the fedora-codewatch mailing list (automatic updates for project code-related events)
Revision 1.8 2002/05/13 18:39:29 cwilper
Added a comment on the -d option with "cvs update"
Revision 1.7 2002/05/09 21:24:44 cwilper
Finished locking section
Revision 1.6 2002/05/09 16:09:03 cwilper
Re-formatted xml and added userinput elements in a couple needed places
Revision 1.5 2002/05/08 00:50:36 cwilper
fixed another missing section closing tag prob
Revision 1.4 2002/05/08 00:47:09 cwilper
fixed minor prob (unclosed tag) at end of in-progress locking section under cvs section
Revision 1.3 2002/05/08 00:44:34 cwilper
- changed emphasis tags to userinput tags where appropriate
- changed note sections to use the note tag
- added chmod note for ant on unix
- started section, 'a quick guide to cvs'... still need to add weak locking notes
Revision 1.2 2002/05/03 22:30:58 cwilper
1) added target detail for the working targets
2) for the cvs "co" command, specified to use -P option
so it doesn't pick up deleted directories
Revision 1.1 2002/05/03 18:50:29 cwilper
moved to devdocs subdir and removed system-specific headers
Revision 1.2 2002/05/02 20:06:56 cwilper
Fixed a couple misspellings and added CVS tags inline.