Hacking The BTK
===============

1) Get the code:
----------------

So, you want to start hacking the BTK, eh?  Good for you.  The first thing
you should do, since the project is under heavy development at the moment,
is to pull down the most current code from the project SVN archive.  If you
hack on a release version of the code, and end up submitting patches to an
old code base, it makes it hard on us, and your patch may never get properly
integrated.  So, do us a favor, do yourself a favor, and always get the
latest code from our Subversion repository.  Here's what you'll need to do 
to get the source:

1a) Get the Boost library

This version of the BTK depends on components from the Boost library,
version 1.33 or later.  Boost is always freely available from 
http://www.boost.org. 

1b) Get the BTK source

Once you've logged in and obtained the Boost library, pull down the latest BTK
source code using your favorite Subversion client:

svn co https://svn.sourceforge.net/svnroot/btk_core btk_core

This command will grab the entire subversion tree for the BTK project, 
(including branches, tags and currently-unreleased projects), and place them
in a directory named "btk" in your working directory.  If you only
want the trunk of the btk_core library, use this command:

svn co https://svn.sourceforge.net/svnroot/btk/btk_core/trunk btk_core

This is just an overview.  For more information (on sourceforge, subversion, 
source code revision managment, etc.) look here:

http://sourceforge.net/svn/?group_id=28435

2) Compile the code:
-------------------

We won't say too much about this here.  See the INSTALL file.  One warning:
this *is* a C++ project, and we make use of many standard C++ features.  So,
you'll need a recent C++ compiler, along with a current standard C++ library 
(including the STL).  We currently use the following compilers and platforms for 
development:

Mac OS X (10.3): g++ 3.2 (the default compiler), g++ 4.0 (MUCH faster compiles!)
Linux: g++ 3.3   

Other compilers may work (if they're reasonably standards-compliant), but sadly,
we don't have the time or equipment to support them ourselves.  If you find the 
BTK useful, and would like to make it work with your favorite platform/compiler,
we would love to have your help!  

3) Familiarize yourself with the code:
-------------------------------------

Again, there's not much to say here, other than you should go through the
code, try to compile the example applications, and maybe attempt to develop
a few of your own.  We're starting to put together some design documents,
and we'll only be adding more documentation in the future.  When it
happens, it'll all be posted at the project website:

http://btk.sourceforge.net

Also, we'll be happy to accept any and all documentation/comment patches
that you're willing to prepare.  So, if you're the type who comments code
as you figure it out, we would be happy to take advantage of you.

4) Talk to the developers:
-------------------------

If you think you've found a bug, or you have a feature you want to
implement, or you just see something wrong that you want to fix, come by
the btk development website at:

http://www.sourceforge.net/projects/btk

and see if anyone else is already working on the same thing.  If not, send
an email to one of the project maintainers, and let us know what you're
working on.  That way, we can devote our time to the other things that need
fixing.  Also, if you're really interested, request to be added to the btk
developer mailing list by going to:

http://lists.sourceforge.net/lists/listinfo/btk-developers

and filling out the subscription form.  It's a private list, but if you're
willing to develop code, we'll be glad to add you.

5) Conform to the standards:
---------------------------

At the moment the coding standards are informal (and perhaps not
universally applied--yet!), but they do exist.  Among the most important:

Naming conventions: 
------------------

Filenames are lower-case only, with words separated by underscores.  Valid
extensions for c++ source files are *.hpp and *.cpp.

Make variable and function names long enough to be descriptive.  We aren't
using FORTRAN--there's no need to be stingy with characters.

Class names are mixed-case, no word spacing, with the first letter of
the class name and the first letter of each word in a name made
upper-case.  For example: Molecule, System, PDBSystem

Functions, and variables are all lower-case, with words separated by
underscores.  For example:  temp_var, rotate_vector, calc_dihedral

Class member variables are to be prefixed with an underscore, and follow
the naming convention for regular variable names:  _sequence, _pos, _flag

Constants, enum names, and macros are to be all-caps, with words separated
by underscores:  PI, ALA, BIG_IMPORTANT_MACRO()

Coding conventions:
------------------

COMMENT YOUR CODE.

Given a choice between Cleverness and Clarity, choose Clarity.

Adopt the 90/10 rule as your new religion:  before you "optimize" something, 
realize that it probably doesn't need optimization.  If it does, talk to 
someone first -- there's probably a better way to "optimize." 

Don't create global variables.

Don't put data in the public interface of classes.

Use std::string instead of char *!!!

Use iostreams instead of C-style IO.

Use the standard library.  Use the STL. 

Use the Boost library whenever practical.

Never return raw, non-const pointers from functions.
(std::auto_ptr<> classes, on the other hand, are OK.)

Specify unsigned when you know a value is never negative.

Use const.  Be const correct.  Declare your functions const when
appropriate.

Use const values and inline functions, instead of macros.

Don't put using declarations in header files, unless they're
scoped by blocks or functions. (In other words: don't pollute the global
namespace).

When you can avoid #including a header, don't.  Use forward declarations
liberally (you will learn to appreciate the compile speed benefits).

Documentation Conventions:
-------------------------

Comment your code!!!

Use C++-style comments instead of C-style comments.

Document your functions, classes and files with doxygen comments.  If you
don't know how to use doxygen, go to:

http://www.stack.nl/~dimitri/doxygen/manual.html

which explains the whole thing.  Alternatively, look around at some of the
other files in the source tree that have been properly doxygenated for
example comments.

6) MAKE SURE IT BUILDS!
-----------------------

The number one, most important rule of distributed development is:

NEVER BREAK THE BUILD!!

If you break the build, you are a bad person.

As such, make sure your code compiles from a clean directory BEFORE 
you check it in.  If there are example applications in your code, 
make sure they build and link too.  If there are test harnesses, make 
sure they build and run to completion.

Since we use the GNU build tools, you'll need to take a few extra steps
in order to build the code, especially if you're using SVN code.  From
a newly-downloaded SVN version of the BTK, the following commands will 
setup, configure and build everything:

autoreconf  (or alternatively: aclocal, autoconf, autoheader, automake)
./configure
make

All of the above applies to patch submitters.  If your patch causes the 
build to break, we probably won't spend much time looking at it, and it 
will never be included. 

7) Make sure it runs.
--------------------

Self-explanatory.  Please do debug your own changes, and if test harnesses
exist, run them on your code.  If necessary, write new test harnesses to 
test your code (submit these, too!)

8) Hand it over:
---------------

Once you've made your fantastic change to the BTK, formatted it, compiled
it and tested it and made sure it runs, it's time to submit.  

If you're a project developer: commit your changes to the repository
directly.  One caveat:  if your change is large, consider tagging the
repository BEFORE committing the change.  Use your best judgment.

If you're a patch submitter: generate a patch to the CURRENT SVN TREE using
diff, gzip the patch, and submit it to the patch manager at the BTK
development site (http://www.sourceforge.net/projects/btk, then click on
"patches").  Make sure you tell us your name and email address, so that we
can add you to the AUTHORS file!

9) Lather, Rinse, Repeat:
------------------------

That was easy, wasn't it?  Yes!  It was!  Feel the power!
Focus it.  Use it.  Hack some more. 
