h1 Architecture
This document explains the architecture of DamageControl. Some sections are slightly out-of-date.
h2 Events
h3 BuildRequestEvent
h3 BuildStartedEvent
h3 BuildProgressEvent
h3 BuildCompleteEvent
h2 Classes
h3 Triggers
Triggers typically monitor some external system and produces a BuildRequestEvent if a build is deemed necessary.
h5 SocketTrigger
This trigger listens for requests on a socket. The request should be a [build configuration] in the form of a [YAML] document, it needs to end with three dots ("...") on an empty line. CVS is typically set up to send this request using netcat ( nc ) from a file also kept in CVS. This makes configuration completely decentralized.
h5 XMLRPCTrigger
This is similar to the SocketTrigger but listens to a [XMLRPC] request over http instead. The [YAML] file should not end with three dots.
h3 BuildScheduler and BuildExecutor
These guys performs a fine dance when a BuildRequestEvent arrives.
h3 Build
This section is quite out-of-date.
A Build represents the process of executing a build. It has one method called execute() that will do essentially two things:
1. Get the latest sources from the SCM
2. Execute a build command that will result in the generation of compulsory build artifacts. The build command may also result in generation of secondary build artifacts and perform deployment operations.
If any of these operations fail, the build will be marked as failed.
A lifecycle object goes through the following lifecycle:
- Prepared (Constructed)
- Getting sources (may fail or succeed)
- Executing (may fail or succeed)
- Analyzing (may fail or succeed)
- Completed
TODO: STATE DIAGRAM
h5 Prepared
This is the initial state that the object will be in after its creation. At this stage it should contain sufficient internal information to carry out steps 2,3 and 4.
At the preparation state it is possible to set information that can also be discovered during the Analyzing state. This information is typically:
- files that were changed since last attempted build
- people who checked in code since last attempted build
Whether or not to record this information during the prepared state or the analyzing state is configurable. Depending on the SCM and build system in use, one or the other may be more appropriate.
h5 Getting latest sources
The build is in this state from the moment an SCM update to the local build machine starts until it is finished.
h5 Executing
While the build command (which will be run as a separate process) is still running, the build is in executing state. If the process itself fails, the build will be marked as failed, marking it with the error message from the operating system.
The standard output/error streams from the build command will be intercepted by DamageControl and written to a log file by the LogWriter.
If the process completes, the decision whether the build failed or not will be deferred until the Analyzing state.
h5 Analyzing
If the build process terminated normally, the status of the build will now be determined. This can be done in a combination of the following ways:
- Analyse the system out and system error log files produced during the Executing state.
- Analyse additional log files produced by the build system.
The process log files and build system log files are likely to contain redundant (but hopefully not contradictory) information. How they are analysed and combined is up to individual build analyser objects. This is configured during the setup of the DamageControl launcher script.
The relevant information from the Analyzing state (such as whether the build failed, why it failed, how long the execution of the tests took etc.) will be set on the build object. This information should not take excessive amounts of memory (log files can be several megabytes).
The build object will then be passed on to publishers that will publish the result of the build to various communication channels
h3 Publishers
The publisher classes are responsible for delivering content to a destination. They subscribe to the hub and respond to process_message() by either delivering content to a destination, or by saving some information that will be delivered later when a destination polls for it.
Currently DamageControl supports IRC and static files (HTML). RSS, Email, Jabber and Yahoo! Messenger(TM) destinations are planned. The content that these publishers deliver is provided by templates.
There is also a Java applet that can be used to monitor build progress. It is not technically speaking a publisher. It is a poller that polls for content (build output redirected to logfiles) on the DamageControl server. It is an excellent way to monitor a build at real-time.
A Status publisher is in progress that collects information on the status of builds in order to respond to XMLRPC requests from polling agents. This will enable monitoring tools integrated with IDEs (Eclipse and IDEA) and standalone applications (a .NET systray applet).
h3 SCM
The SCM classes are responsible for all interaction with the physical SCMs. They are not full blown Ruby wrappers for the SCM's native APIs, but include functionality that is required for DamageControl:
- Installing DamageControl triggers (using nc - netcat) in repositories
- Checking out latest code
- Parsing URL-like strings that identifies a repository
- Getting/guessing email addresses from users
h3 CruiseControl integration
To be completed
h2 Glossary
h3 Build artifacts
h3 Compulsory
- Compiled code (if appliccable)
- Test reports
h3 Optional
- Packaged code
- Documentation
h3 SCM
SCM stands for Source Control Management systems. Examples are CVS, Subversion (SVN), StarTeam, Perforce, Visual Source Safe (VSS) etc. Currently only CVS and SVN are supported.