Introduction
Urbancode developed Anthill to make it easier to automate the build process among a group of developers using Apache Ant.
Anthill allows multiple users to work together and consistently access only the latest build, complete with changes from all programmers working on a project. This eliminates messy conflicts that arise when multiple users are working with the same source code!
We decided the best way to unlock the source code assets within a company was to dedicate a portion of an intranet to a project library. This library would contain home pages for every project within the organization.
Anthill creates a central project library that is updated manually and kept current, allowing the sharing of source code and compiled libraries within an organization.
Anthill performs a checkout from the source repository of the latest version of a project before every build and tags the repository with a unique build number. Anthill then updates a project intranet site with artifacts from the latest build.
It's a model developed from Open Source projects. Basically, Anthill instantly internalizes Open Source within an organization.
Anthill is compatible with version 1.3 and 1.4 of Apache Ant. Unlike other Apache Ant build tools, Anthill is designed to be as non-intrusive as possible and does not require cumbersome build additions. Anthill is Open Source and released under a Mozilla-like license.
Anthill is a product of Urbancode Software Development and falls under the protection of the Urbancode Public License Version 1.0, available at http://stage.urbancode.com/projects/anthill/License_UPL.txt
You may download the most recent version of Anthill at the Urbancode website at: http://www.urbancode.com/projects/anthill/download/
Ideally, you should have a central Anthill server that is used to build and publish all your projects. If you have more than one CVS server, then you may want one Anthill installation per CVS server.
Future releases of Anthill will lock the CVS project while performing a checkout to minimize the possibility of data corruption.
A CVS repository can only be locked locally by a process running on the same machine. So it makes sense to install Anthill on the same machine as your CVS server.
If you choose to install Anthill in your 'C:\programs' directory and unpackage the Anthill distribution into that directory, the 'C:\programs\anthill\' directory will be the Anthill root directory.
Then, unpack the Anthill distribution to the '/usr/local/' directory.
The '/usr/local/anthill/' directory would then be the Anthill root directory.
The first time you access this page you will be asked for the Anthill home directory (this is simply the absolute path to the directory where Anthill is installed.
In the above examples the root directories were 'C:\programs\anthill\' and '/usr/local/anthill/'.)
From the main Anthill Build System page follow the link entitled Anthill Properties. On the form that appears modify the anthill.repository.cvs.root property and the anthill.mail.host and anthill.mail.from properties.
From the main Anthill Build System page follow the link entitled "Create New Project".
Anthill ships with two predefined schedules, a stoppedSchedule and a default schedule.
The Example project is set to the stoppedSchedule. You can change that so that Anthill will build the Example project according to the schedule you set.
Running the Example Anthill Project
Anthill Server Requirements
Servlet Containers
Anthill may be configured for any Java servlet container 2.2+ compatible web container, but has only been tested with the following servlet containers:For the administration of the system, you can use a regular web browser. Microsoft Internet Explorer 4+ or Netscape 4+ are recommended, but Mozilla and Opera will also work.
Once Anthill is installed on your computer and it's started up in Tomcat, you can open it from a browser directed to the address you specified as the anthill.server in the main Anthill properties.
Anthill's main screen will allow the user to view all of the current Ant projects being worked on, and the build schedules for each of them.
There are five sections of the main screen:
At the top of the main screen is the link to the main Anthill properties. These settings control where the system accesses Anthill, and where the CVS repository is located.
anthill.ant.home
Enter location of Ant .jar file
anthill.version.adapter
Enter class of CVS version adapter.
Currently, the UrbanCode Version Adapter is implemented, and the default value should not be changed. The option to change it is there should someone have a desire to develop their own adapter.
This controls the format of the version number Anthill uses during scheduled builds.
This value defaults to:
major.minor.build (for example 4.5.234)
Anthill only increases the build number during scheduled builds. To increase major or minor build numbers a build must be forced. Refer to section on unscheduled builds for information on how to force a build.
When building with branches with the default anthill.repository.adapter, the format of the version number will be different. There will be only one number, usually prefaced by the branch name.
Example: Pluto_Branch-36
anthill.repository.adapter
Enter the class name of the CVS repository adapter.
The repository adapter is responsible for interaction with the source control repository.
Currently, only the CVSRepositoryAdapter is supported, but the option is there to change it should someone have a desire to develop their own adapter.
This might be useful if someone wished to use Anthill with other source repositories such as Perforce, Merant PVCS, or Microsoft Visual SourceSafe.
anthill.repository.cvs.root
Enter the CVS ROOT used to log in to CVS.
This is the CVS connection information with the following information:
Note: Please keep in mind that if you are using pserver authentication, then the user must log into CVS on the machine running Anthill. (Logging in manually will allow the CVS client to store the CVS password for future use.) anthill.work.dir
Enter the location Anthill will use to temporarily copy files to as it checks out the CVS project source during a build.
This directory will always be relative to the directory Tomcat is started from.
anthill.publish.dir.default
Specify the location to place build artifacts after a build is completed. Each project starts with a default value of publishDir.
anthill.mail.host
Specify the mail server IP address or DNS name.
anthill.mail.from
Specify the name that will show up on automatic emails sent by Anthill after builds.
anthill.server
Specify the URL address where Anthill will be accessed on server.
This will be the address you use to access Anthill with your browser.
Note: context name in the URL has to be the same as the name of the .war file.
anthill.lock.version.file
This drop-down box allows the user to select to turn off or on the option to lock a CVS version file.
anthill.dependency.target
Enter the Ant target to execute when building dependencies.
This allows the user to use a different build process for stand-alone projects and projects that are part of a dependency group.
anthill.dependency.artifact.property
Enter the property name to be passed to the Ant script when executing a dependency target whose value will be the directory containing the build artifacts
For example, if you used the default property of "dependency.artifact.property" then you would refer to the build artifact directory from your Ant script as: ${dependency.artifact.dir}"
The second section of the main screen allows users to access, add, and edit properties of all projects. Each project will appear in the left column. User may click the project name to view the project's properties, "site" to view the project's website or build artifacts, or "build" to force a build before scheduled or build with a specified build number.
Create a new Project
To create a new project, click on the "Create New Project" link at the bottom of the Projects list.
This link will open a new properties screen. Enter the following properties to create the new project:
anthill.project.name
Enter the name of the new Anthill project.
When naming a project, it is advisable not to use spaces. This is known to cause problems on some platforms.
anthill.version.adapter
See anthill.version.adapter in main Anthill settings.
anthill.version.file
Enter the path of the version file relative to the project root.
The version file must be in CVS. The version file is a text file that contains the version of the project.
anthill.repository.adapter
See anthill.repository.adapter in main Anthill settings.
repository.cvs.work.dir
Enter the name of the directory where CVS will check out the project. This must be relative to the directory path. The path will be relative to the current working directory.
repository.cvs.module
Enter this project's CVS module.
The paths of the version file, build script, and publish script, are all relative to the CVS module. For example, if the CVS module is Anthill and the build script is Anthill/build/build.xml, the location of the build script is build/build.xml.
repository.cvs.root
See anthill.repository.cvs.root in the main Anthill properties.
repository.cvs.anthill.user
Enter the name of the CVS user account used by Anthill.
All revisions committed by this user will be filtered out when determining whether a build is required.
repository.cvs.branch
Enter the name of the CVS branch that Anthill is to build. (Most of the time this will be blank.)
For building with branches, refer to the note under the anthill.version.adapter about version numbers for branches.
anthill.build.script
Enter the path to the build script in the project root directory.
anthill.publish.script (optional)
Enter the path to the publish script in the project root directory. If the user doesn't specify a publish script, they should do the publishing in their build script.
anthill.publish.dir
Enter the path to which the build artifacts are to be moved.
Most of the time this can be left empty. By default, Anthill will place all publish artifacts in the publishDir/${project.name} directory under the Anthill root. Project artifacts will then be available via browser at the url:
anthill.publish.url
Enter the url where the build artifacts are available.
Most of the time this can be left empty. By default, Anthill will place all publish artifacts in the publishDir/${project.name} directory under the Anthill root. Project artifacts will then be available via browser at the url:
Enter users that should receive build logs each time this project is built. Enter the user's name in the first box, and the user's email address in the second box.
anthill.build.params
Enter additional build parameters to be referenced in ant build scripts.
The first box is for the property name; the second is its associated value. These are passed as system properties when Ant is executed as in this example:
java … -Dprop_name=prop_value org.apache.tools.ant.Main …
anthill.build.ant.params
Enter parameters to be passed to Ant during the build process. These are passed as command line parameters to Ant as in this example:
java … org.apache.tools.ant.Main -prop_name=prop_value …
anthill.publish.params
Parameters to be passed to Ant during the publish process.
The first box is for the property name; the second is its associated value. These are passed as system properties when Ant is executed as in this example to the JVM:
java … -Dprop_name=prop_value org.apache.tools.ant.Main …
anthill.publish.ant.params
Parameters to be passed to Ant during the publish process.
These are passed as command line parameters to Ant as in this example:
java … org.apache.tools.ant.Main -prop_name=prop_value …
anthill.schedule
This dropdown box specifies which build schedule will be used for this project. If a new schedule is needed, refer to the instructions for the Schedules.
Click on the name of the project to edit its properties. This will bring up the properties page for the project. Most fields may be edited at any time.
The delete checkbox
Some fields have a delete checkbox to remove previously entered data. To use these, click the checkbox and hit the submit button at the bottom of the page. This will delete selected lines.
Beside each project is a link to a project's website.
This link will be to the address specified in the Project Properties as the anthill.publish.url. If this property is left empty, the site link will default to the address specified in main Anthill property: anthill.publish.dir.default. The site link will allow the project artifacts to be viewed.
Do an unscheduled build
Click "Build" in the far right column of the project category to force an unscheduled build for a project. This can be done at any time, and will run Ant's build script.
When the next scheduled build time arrives, Anthill will check to see if modifications have been made since the last build (good or failed.) If changes have not occurred, Anthill will not do another build unless Force Build is checked.
Force Build checkbox
If no changes have been made since the previous build, and you still wish to do another build, you must use this checkbox to do the build.
Build as Version
Use the build as version box to specify a build number.
Note: This should be in the proper format as defined by the anthill.version.adapter.
Anthill allows users to specify different projects as dependencies of other projects.
Doing builds of dependent projects often becomes cumbersome because a dependant needs the artifacts from its dependency builds to successfully build. When there is more than a one-to-one relationship, it simply becomes unmanageable to do it manually.
Anthill allows users to set up dependency groups to coordinate the build order of related projects and eliminate the need to manually manipulate the build artifacts of related projects.
Dependency group establishes a "dependant" (project) and a "dependency" (sub-project) relationship between projects.
Anthill automatically builds all dependencies first and makes the build artifacts available to the dependant.
Create a new dependency group
Click on the "Create New Dependency Group" link at the bottom of the screen. This will open a new properties screen for dependency groups.
Group Name
Name your group in this text box. This is how your group will show up on the dependency group list on the main screen.
New Member
Select the first project to be a member of your dependency group from this dropdown box. All projects currently created will be in the drop-down menu. Click update to add the member.
Reopen the group and select the second member from the drop-down list.
Repeat this process for as many members as you need for each group.
Dependency Drop-Down
After the members of a group have been specified, you may then choose the relationships of each member. Once a project is assigned as a dependency of another project, it will disappear from the drop-down list.
Select the schedule to use for builds of your dependency group. All schedules currently created will be in the drop-down menu.
Anthill will build each project in the group on this schedule. This will not affect the pre-existing build schedules for each project.
Schedules
The Schedules box keeps track of the schedules that Anthill uses to automatically conduct builds of Ant projects.
Users may create customized schedules for each project, or use the same schedules for many projects.
Upon install, Anthill will have two default schedules: stoppedSchedule, and default.
Create a new schedule
To create a new schedule, click the "Create New Schedule" link at the bottom of the schedule box. This will open a properties screen that will allow you to name your schedule and specify the start time and the interval at which projects using this build schedule will use.
Schedule Name
Name your schedule in this box. Do not use spaces.
Build Interval
Enter the number of minutes between each build.
Start Time
Enter the time to begin this build schedule.
This will be the start time when Anthill is started, or restarted. After the initial time, Schedules will only run at the specified build interval.
The exact start time will be the time of the computer Tomcat is running on.
stoppedSchedule
Anthill is equipped with a stoppedSchedule to be used if you need to stop builds for a period of time. Because Anthill's very purpose is to perform builds on a regular basis, all projects must select a schedule for builds. This schedule was created as a workaround for situations where it might be wise to delay builds temporarily.
The Build Queue is at the bottom of the main screen. When a project goes into a scheduled build or a forced build, it will appear in the build queue.
When the build is complete, the project will disappear from the build queue. If no projects are currently being built, this list will be empty.
You will need to hit refresh for page to update and view precisely whether or not a project is currently being built.
To refresh the main screen, click the "Refresh" link at the top of the main screen beneath the "Welcome to the Anthill Build System" greeting.
This will refresh the page without reposting form data from the user's last action, and show projects currently in build queue.
If you are installing Tomcat through via RPM, make sure the owner of Tomcat can write to Tomcat home directory. The user running Tomcat needs to have write permission to its own home directory, because it needs to write the anthill.properties file. View the bug log for further information.
Urbancode encourages our users to contribute their thoughts on Anthill with the rest of our community of users with our Anthill newsgroup at:
http://lists.urbancode.com/pipermail/anthill/
For updates on Anthill, you may also join the Anthill mailing list at:
http://lists.urbancode.com/mailman/listinfo/anthill/
Feel free to contact the developers of Anthill at Urbancode Software development for more information about Anthill, or to voice your opinion.
Urbancode, Inc.
Anthill is available coded in Java and HTML at http://www.urbancode.com/projects/anthill/default.jsp
Edit an existing project's properties
Open a Project's website
Dependency Groups
Schedule
Build Queue
Refresh
Appendices
Appendix A: Troubleshooting
Permission Problems:
Installing Tomcat through RPM
Configuration issues:
Anthill Newsgroup and Mailing List
Contacting Urbancode
2044 Euclid Avenue, Suite 600
Cleveland, OH 44115
voice:(216)858.9000
toll free:(878)858.4599
fax:(216)858.9602
email:cindy@urbancode.com
JavaDoc and HTML