doc.devdocs.devguide.html Maven / Gradle / Ivy
Show all versions of fcrepo-client Show documentation
Developer's Guide 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 [email protected] (where
username is your login name).
Unix users: type
ssh [email protected]. Your ssh
client should log you in automatically. Type
exit to logout.
OPTIONAL: Set your CVSROOT
environment variable to
:ext:[email protected]:/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.
Note
If you're on a Unix system
and plan to use the version of ANT included in the res/
directory, you should run chmod 755
<work_path>/mellonres/ant/bin/* to ensure
that the shell script that invokes ant is executable.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.
A. A Quick Guide to Using CVS
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.
Note
If a file
is binary, you must use -kb
or the file will be mangled in the repository.
For normal text files, you should not use
-kb.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.
Note
Under normal circumstances, deleted files can be recovered from
the repository, so the delete operation will only make the file
invisible to those who have the most recent copy of the code.
You may check out an old version of the deleted file at
any time.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)
B. Revision History
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.