Wiki Navigation

Developer Guide

This page contains information for developers who want to work with the HoneyClient source code.

Repository Layout
Code Stability Status
Anonymous Checkout
Authenticated Checkout
Committing Code
Packaging

Repository Layout

Like most SVN repositories, the honeyclient project repository is split into three subdirectories: trunk, branches, and tags.

Version Format

All project versions follow the syntax of MAJOR.MINOR.MACRO. For example, the code version 1.2.3 reflects a MAJOR version of 1, a MINOR version of 2, and a MACRO version of 3. Each part of the version number must be an integer, and must not be greater than 6 digits.

Normal project evolution is tracked using MAJOR.MINOR milestones. Whenever a logical set of features/improvements are added to the code (and a milestone is completed), the version is incremented by +0.1.0. Whenever bugs are fixed/resolved between milestones, the version is incremented by +0.0.1. Thus version 6.5.2, represents code completing all milestones up to and including 6.5, with 2 bugs resolved in the code.

Note: Unfortunately, perl does not like representing package versions as MAJOR.MINOR.MACRO. As such, we guarantee that the MINOR number is always a single digit integer (0-9) inclusive, in order to treat MAJOR.MINOR.MACRO as MAJOR.MINORMACRO in the perl code, directly. Thus, version 6.5.2 is represented in the perl code as 6.52.

Trunk

The trunk directory is used to store the most current (unstable) version of the project. Primary development of the project code is performed in this directory. Normally, code is committed to the trunk, until a point in time when the trunk source code becomes stable and ready for release. At that time, a release branch is created, which contains a complete copy of this stabilized code.

Branches

The branches directory is used to store modified copies of the project (per MAJOR.MINOR version increment). This directory includes release branches, bug fix branches, and experimental branches.

Branches and Tags Subdirectories

The branches and tags directories both include the following subdirectories:

rel (For stable releases)
bug (For bug fixes)
exp (For experimental code)

Structural Visualization

The following diagram provides an example about how this repository is organized:

 honeyclient:
  |
  +--trunk
  |   |
  |   +--project-files
  |
  +--branches
  |   |
  |   +--rel
  |   |   |
  |   |   +--0.9
  |   +--bug
  |   +--exp
  |
  +--tags
      |
      +--rel
      |   |
      |   +--0.9.1
      +--bug
      +--exp

Code Stability Status

The following page provides the most latest status of the trunk branch. This can be useful in determining whether or not you want to try the trunk or the latest stable branch.

Anonymous Checkout

To anonymously checkout the latest stable branch of the code, type:

svn co svn://svn.honeyclient.org/honeyclient/tags/rel/1.0.1

Authenticated Checkout

All authenticated SVN checkouts are performed via the svn+ssh protocol. This requires specifying the URL prefix of svn+ssh://username@@svn.honeyclient.org/svn/honeyclient for all SVN commands. For example, to checkout the trunk directory, you will need to type:

svn co svn+ssh://username@svn.honeyclient.org/svn/honeyclient/trunk

Notes:

The RSA key fingerprint of svn.honeyclient.org is 34:48:32:85:f7:99:e8:9f:16:e8:ae:bc:eb:b0:1a:5b.
It is recommended that you enable SSH keys on the server, in order to speed up SVN operations.

Committing Code

In order to commit code into this repository, it is highly recommended that you download and install the SVA (aka. svnauto) RubyGem, in order to easily use the repository. SVA is simply a Ruby-based tool, that wraps around subversion to perform multiple SVN operations, in sequence. This tool provides an automated way to create and manage release, bug, and experimental branches of code.

Installing SVA

1. On your local system, verify that you have the Ruby interpreter, OpenSSH, and Subversion installed. For Cygwin-based Windows environments, you can use the Cygwin installer to easily install Ruby, OpenSSH, and Subversion.

Note: For existing Cygwin environments, please be sure to upgrade your base environment prior to installing SVA, as RubyGems requires a fairly recent version of Cygwin.

2. Install RubyGems on your local system. This usually requires downloading the latest rubygems*.tgz file, extracting the archive contents into a new temporary subdirectory, and finally calling ruby setup.rb within that subdirectory.

3. Once RubyGems is installed, then install SVA by simply typing:

gem install svnauto --include-dependencies

4. Once installed, to update SVA to the latest version, type:

gem update svnauto --include-dependencies

Adding the SVN repository to SVA

As stated in the SVA quick start guide, before you can use SVA to access this SVN repository, you need to provide SVA with initial information. The following example describes this process.

1. Add a new SVN repository to SVA:

sva config --add

2. SVA will then as you to name this repository. Call it svn.honeyclient.org.

Repository Name (used with sva -r): svn.honeyclient.org

3. SVA will ask you for the repository URL. Specify your username in the following example:

Repository URL: svn+ssh://username@svn.honeyclient.org/svn

4. SVA will ask you where you want your local copies of the repository to be located. Specify ~/src as an example.

Directory where checkouts go (can be relative to ~/): |develop/svn_honeyclient_org| ~/src

Checking out the trunk branch

To check out the trunk branch of the SVN repository, follow this example.

1. Call SVA with the checkout option.

sva checkout

2. SVA will ask which SVN repository to use; specify the svn.honeyclient.org one.

Repositories:
1. svn.honeyclient.org (svn+ssh://username@svn.honeyclient.org/svn)
Please choose a repository: 1

3. SVA will then ask which project to check out; specify honeyclient.

Fetching project list from repository, please wait...
Projects:
1. honeyclient
Please choose a project: 1

Once specified, SVA will download a local copy of the trunk branch into ~/src/honeyclient-trunk.

Checking out a release-specific branch

For example, to check out the 0.9 release branch of the SVN repository, follow these steps.

1. Call SVA with the checkout —release 0.9 options.

sva checkout --release 0.9

2. SVA will ask which SVN repository to use; specify the svn.honeyclient.org one.

Repositories:
1. svn.honeyclient.org (svn+ssh://username@svn.honeyclient.org/svn)
Please choose a repository: 1

3. SVA will then ask which project to check out; specify honeyclient.

Fetching project list from repository, please wait...
Projects:
1. honeyclient
Please choose a project: 1

Once specified, SVA will download a local copy of the trunk branch into ~/src/honeyclient-rel-0.9.

Creating a new release branch

Assume you want to create a 0.9.2 honeyclient release branch, based off of the trunk branch. Follow the following steps.

1. We assume your local copy of the trunk is in ~/src. As such, change to the ~/src/honeyclient-trunk directory.

cd ~/src/honeyclient-trunk

2. Make sure your local copy of the trunk is up to date. Resolve any conflicts.

svn update

3. Make sure you've committed all your local changes to the trunk back to the remote repository. Resolve any conflicts.

svn commit

4. Tell SVA to create an 0.9.2 release branch.

sva release 0.9.2

5. SVA may ask to create the 0.9 release branch, if it has not been already created. Specify yes.

Create honeyclient release branch 0.9? y

6. Among other messages, SVA will confirm when the 0.9.2 release branch succeeded.

Creating 0.9.2 release tag for honeyclient

7. Lastly, SVA will create a new local copy of the release branch as ~/src/honeyclient-rel-0.9 on your system.

Fixing bugs

Between version releases, it's possible to fix bugs that pertain to the latest version release — without having to merge all code changes between last release branch and the trunk. SVA provides a convenient way to create "bug" branches, where each bug is assigned a number, which is tied to the ticket that describes the issue/bug in more detail.

At a high level, the bug fixing process can be described as:

Create a new bug fix branch, by copying all code from the latest release branch.
Fix the bug on the bug fix branch.
Test and commit your code changes back to the bug fix branch.
Merge your code changes from the bug fix branch to the release branch.
Merge your code changes the bug fix branch to the trunk.
Make a new release branch.

Creating a new bug branch

Assume ticket #42 referred to a bug reported in the honeyclient code, but no other developer has been assigned to fix the bug yet.

1. We assume your local copy of the trunk is in ~/src. As such, change to the ~/src/honeyclient-trunk directory.

cd ~/src/honeyclient-trunk

2. Tell SVA to create a new bug branch, called 42.

sva bug 42

3. If the bug branch has not already been created, SVA will confirm that you want to create this new branch, based upon the latest release branch (in this example, we use the 0.9 branch). Specify yes.

Create bug fix branch for bug 42 off release honeyclient/42? y

4. SVA will create a new local copy of the bug branch as ~/src/honeyclient-bug-42 on your system.

5. As you work on fixing/resolving this bug, be sure to regularly commit your changes back to the bug branch and download updates from the remote repository. This will allow other developers to assist in the bug fix process, if needed.

Checking out an existing bug branch

Assume ticket #42 referred to a bug reported in the honeyclient code, and other developers have made progress on fixing the bug but further revisions are required.

1. We assume your local copy of the trunk is in ~/src. As such, change to the ~/src/honeyclient-trunk directory.

cd ~/src/honeyclient-trunk

2. Tell SVA to create an existing bug branch, called 42.

sva bug 42

3. SVA will create a new local copy of the bug branch as ~/src/honeyclient-bug-42 on your system.

4. As you work on fixing/resolving this bug, be sure to regularly commit your changes back to the bug branch and download updates from the remote repository. This will allow other developers to assist in the bug fix process, if needed.

Closing the bug

Continuing the previous example further, assume you have completed all revisions to the ~/src/honeyclient-bug-42 branch and are ready to merge these changes back into the latest release branch and back into the trunk.

1. Change to the ~/src/honeyclient-bug-42 directory.

cd ~/src/honeyclient-bug-42

2. Make sure your local copy of the bug branch is up to date. Resolve any conflicts.

svn update

3. Make sure you've committed all your local changes to the bug branch back to the remote repository. Resolve any conflicts.

svn commit

4. Tell SVA to close the bug.

sva bug --close 42

5. SVA will ask you to confirm the merges into the latest release branch (0.9, in this example) and also into trunk. Specify yes for both prompts.

Merge bug fix branch for bug 42 to release honeyclient/0.9? y
Merge bug fix branch for bug 42 to honeyclient/trunk? y

6. Lastly, confirm that your changes were merged into both branches, by checking out / updating your local copies of the honeyclient-trunk and honeyclient-rel-0.9 branches.

Experimental code

Assume that you'd like to make a large set of changes to the trunk that will greatly affect the stability of the code. Perhaps these experimental changes may conflict or affect large portions of the trunk. SVA provides a way to manage these experimental branches and migrate changes between experimental branches and the trunk.

Creating a new experimental branch

Assume you would like to implement a new feature called "foo" within the honeyclient codebase, by creating a new experimental branch.

1. Tell SVA to create a new experimental branch with the name of "username-foo". Usernames are used as unique identifiers, as it is easy to identify which experimental branch belongs to which developer.

sva exp username-foo

2. SVA will then confirm the creation of this new branch. Specify yes.

Create experimental branch username-foo off honeyclient/trunk? y

3. Once complete, SVA will create and checkout a local copy of this branch in the directory ~/src/honeyclient-exp-username-foo.

Checking out an existing experimental branch

Continuing from the previous example, assume you want to checkout an existing experimental branch, named "username-foo".

1. To do this, simply pass the SVA checkout command the experimental branch name, by typing the following.

sva co -e username-foo

2. Once complete, SVN will download the latest version of this branch into your ~/src/honeyclient-exp-username-foo directory.

Merging trunk changes into an experimental branch

Continuing from the previous example, assume the trunk has changed and you would like to incorporate those changes back into your experimental branch.

1. Make sure your local copy of your experimental branch is up to date. Resolve any conflicts.

svn update

2. Make sure you've committed all your local changes to your experimental branch back to the remote repository. Resolve any conflicts.

svn commit

3. Tell SVA to merge trunk changes into the experimental branch.

sva exp --up username-foo

4. Update your local copy of your experimental branch, to reflect these changes.

svn update

Merging experimental changes into a trunk branch

Continuing from the previous example, assume you are now ready to merge your experimental changes back into the trunk.

1. Make sure your local copy of your experimental branch is up to date. Resolve any conflicts.

svn update

2. Make sure you've committed all your local changes to your experimental branch back to the remote repository. Resolve any conflicts.

svn commit

3. Tell SVA to merge trunk changes into your experimental branch.

4. Once this merge is complete, update your local copy of your experimental branch. Resolve any conflicts.

svn update

5. Verify your code and the trunk code is working properly. Resolve any conflicts and commit any changes you make back to the remote repository.

6. Once all testing is complete, tell SVA to merge your experimental changes back into the trunk.

sva exp --down username-foo

7. Once this merge is complete, update your local copy of the trunk. Confirm the changes you've made.

cd ~/src/honeyclient-trunk
svn update

Notes

For more information on this process, please see the SVA manual, available at: http://software.pmade.com/svnauto/pages/show/Documentation

Packaging

Here's how to re-package the HoneyClient code into separate Agent, Manager, and Util packages.

HoneyClient::Util

1. From the root SVN directory, create an initial Util package directory.

perl create_pkg_dir.pl HoneyClient-Util

If successful, then this should automatically create HoneyClient-Util/

2. Next, you'll need to generate Makefile.PL

cp create_pkg_makefile.pl HoneyClient-Util
cd HoneyClient-Util
perl create_pkg_makefile.pl HoneyClient-Util

3. Remove create_pkg_makefile.pl from the HoneyClient-Util subdirectory.

rm create_pkg_makefile.pl

4. Edit the Makefile.PL and update the version line.

5. Generate unit test code, for the package.

inline2test etc/inline2test.conf

If successful, then this should automatically create any unit test code, located at t/*.t.
Note: inline2test is a perl script that is part of the Test::Inline package. If this script is not already in your path, then you may need to install it via CPAN.

6. Generate Makefile

perl Makefile.PL

If successful, then this should automatically create Makefile.

7. Generate MANIFEST

make manifest

8. Generate HoneyClient-Util-X.XX.tar.gz

make dist

If successful, then this should automatically create the HoneyClient-Util-X.XX.tar.gz archive.
This archive is now ready to be used and installed onto other systems via CPAN.

9. Once you've copied the archive out of this package directory, you'll want to remove the generated HoneyClient-Util directory, to do final cleanup.

cd ..
rm -r HoneyClient-Util/

HoneyClient::DB

1. From the root SVN directory, create an initial DB package directory.

perl create_pkg_dir.pl HoneyClient-DB

If successful, then this should automatically create HoneyClient-DB/

2. Next, you'll need to generate Makefile.PL

cp create_pkg_makefile.pl HoneyClient-DB
cd HoneyClient-DB
perl create_pkg_makefile.pl HoneyClient-DB

3. Remove create_pkg_makefile.pl from the HoneyClient-DB subdirectory.

rm create_pkg_makefile.pl

4. Generate unit test code, for the package.

inline2test etc/inline2test.conf

5. Generate Makefile

perl Makefile.PL

If successful, then this should automatically create Makefile.

6. Generate MANIFEST

make manifest

7. Generate HoneyClient-DB-X.XX.tar.gz

make dist

If successful, then this should automatically create the HoneyClient-DB-X.XX.tar.gz archive.
This archive is now ready to be used and installed onto other systems via CPAN.

8. Once you've copied the archive out of this package directory, you'll want to remove the generated HoneyClient-DB directory, to do final cleanup.

cd ..
rm -r HoneyClient-DB/

HoneyClient::Agent

1. From the root SVN directory, create an initial Agent package directory.

perl create_pkg_dir.pl HoneyClient-Agent

If successful, then this should automatically create HoneyClient-Agent/

2. Next, you'll need to generate Makefile.PL

cp create_pkg_makefile.pl HoneyClient-Agent
cd HoneyClient-Agent
perl create_pkg_makefile.pl HoneyClient-Agent

3. Remove create_pkg_makefile.pl from the HoneyClient-Agent subdirectory.

rm create_pkg_makefile.pl

4. Generate unit test code, for the package.

inline2test etc/inline2test.conf

5. Generate Makefile

perl Makefile.PL

If successful, then this should automatically create Makefile.
Note: If you attempt to run this command on a Unix system, then when perl scans the system for missing dependencies, it will find that some of the Windows-based packages may be missing. This artifact is normal and you should skip any attempts that CPAN tries to make to auto-install these packages.

==> Auto-install the X mandatory module(s) from CPAN? [y] n
==> The module(s) are mandatory! Really skip? [n] y

6. Generate MANIFEST

make manifest

7. Generate HoneyClient-Agent-X.XX.tar.gz

make dist

If successful, then this should automatically create the HoneyClient-Agent-X.XX.tar.gz archive.
This archive is now ready to be used and installed onto other systems via CPAN.

8. Once you've copied the archive out of this package directory, you'll want to remove the generated HoneyClient-Agent directory, to do final cleanup.

cd ..
rm -r HoneyClient-Agent/

HoneyClient::Manager

1. From the root SVN directory, create an initial Manager package directory.

perl create_pkg_dir.pl HoneyClient-Manager

If successful, then this should automatically create HoneyClient-Manager/

2. Next, you'll need to generate Makefile.PL

cp create_pkg_makefile.pl HoneyClient-Manager
cd HoneyClient-Manager
perl create_pkg_makefile.pl HoneyClient-Manager

3. Remove create_pkg_makefile.pl from the HoneyClient-Manager subdirectory.

rm create_pkg_makefile.pl

4. Generate unit test code, for the package.

inline2test etc/inline2test.conf

5. Generate Makefile

perl Makefile.PL

If successful, then this should automatically create Makefile.
Note: If you attempt to run this command in a Cygwin environment, then when perl scans the system for missing dependencies, it will find that some of the Linux-based packages may be missing. This artifact is normal and you should skip any attempts that CPAN tries to make to auto-install these packages.

==> Auto-install the X mandatory module(s) from CPAN? [y] n
==> The module(s) are mandatory! Really skip? [n] y

6. Generate MANIFEST

make manifest

7. Generate HoneyClient-Manager-X.XX.tar.gz

make dist

If successful, then this should automatically create the HoneyClient-Manager-X.XX.tar.gz archive.
This archive is now ready to be used and installed onto other systems via CPAN.

8. Once you've copied the archive out of this package directory, you'll want to remove the generated HoneyClient-Manager directory, to do final cleanup.

cd ..
rm -r HoneyClient-Manager/

Managing CPAN Dependency Bundles

Starting with Honeyclient v1.0.1, we use CPAN Bundles to simplify the installation of all Perl prerequisites.

Download in other formats:

Plain Text

Wiki Navigation

TracNav menu

Methodologies

Developer Guide

Repository Layout

Version Format

Branches and Tags Subdirectories

Structural Visualization

Code Stability Status

Anonymous Checkout

Authenticated Checkout

Committing Code

Installing SVA

Adding the SVN repository to SVA

Checking out the trunk branch

Checking out a release-specific branch

Creating a new release branch

Fixing bugs

Creating a new bug branch

Checking out an existing bug branch

Closing the bug

Experimental code

Creating a new experimental branch

Checking out an existing experimental branch

Merging trunk changes into an experimental branch

Merging experimental changes into a trunk branch

Notes

Packaging

HoneyClient::Util

HoneyClient::DB

HoneyClient::Agent

HoneyClient::Manager

Managing CPAN Dependency Bundles

Download in other formats: