Abuild Users' Manual
   Next

Abuild Users' Manual

For Abuild Version 1.1.6, June 30, 2011

Jay Berkenbilt

Copyright © 2007-2011 Jay Berkenbilt, Argon ST

This software and documentation may be distributed under the terms of version 2 of the Artistic License which may be found in the source and binary distributions. They are provided “as is” without express or implied warranty.

Table of Contents

Notes For Users of Abuild Version 1.0
How to Read This Manual
Acknowledgments
Notes About Documentation Formatting
I. Quick Start
1. Introduction
1.1. Abuild Overview
1.2. Typographic Conventions
1.3. Abuild Version Numbers and Release Policy
1.3.1. Abuild Version Numbers
1.3.2. Backward Compatibility Policy
1.4. Design Features
2. Building and Installing Abuild
2.1. System Requirements
2.2. Building Abuild
2.3. Installing Abuild
2.4. Additional Requirements for Windows Environments
2.5. Version Control Considerations
3. Basic Operation
3.1. System Considerations
3.2. Basic Terminology
3.3. Compiler Selection
3.4. Building a C++ Library
3.5. Building a C++ Program
3.6. Building a Java Library
3.7. Building a Java Program
II. Normal Operation
4. Build Items and Build Trees
4.1. Build Items as Objects
4.2. Build Item Files
4.3. Build Trees
4.4. Build Forests
4.5. Special Types of Build Items
4.6. Integrating with Third-Party Software
5. Target Types, Platform Types, and Platforms
5.1. Platform Structure
5.2. Object-Code Platforms
5.3. Output Directories
6. Build Item Dependencies
6.1. Direct and Indirect Dependencies
6.2. Build Order
6.3. Build Item Name Scoping
6.4. Simple Build Tree Example
7. Multiple Build Trees
7.1. Using Tree Dependencies
7.2. Top-Level Abuild.conf
7.3. Tree Dependency Example
8. Help System
9. Telling Abuild What to Build
9.1. Build Targets
9.2. Build Sets
9.2.1. Example Build Set Invocations
9.3. Using build-also for Top-level Builds
9.4. Building Reverse Dependencies
9.5. Traits
9.5.1. Declaring Traits
9.5.2. Specifying Traits at Build Time
9.5.3. Example Trait Invocations
9.6. Target Selection
9.7. Build Set and Trait Examples
9.7.1. Common Code Area
9.7.2. Tree Dependency Example: Project Code Area
9.7.3. Trait Example
9.7.4. Building Reverse Dependencies
9.7.5. Derived Project Example
10. Integration with Automated Test Frameworks
10.1. Test Targets
10.2. Integration with QTest
10.3. Integration with JUnit
10.4. Integration with Custom Test Frameworks
11. Backing Areas
11.1. Setting Up Backing Areas
11.2. Resolving Build Items to Backing Areas
11.3. Integrity Checks
11.4. Task Branch Example
11.5. Deleted Build Item
12. Explicit Read-Only and Read/Write Paths
13. Command-Line Reference
13.1. Basic Invocation
13.2. Variable Definitions
13.3. Informational Options
13.4. Control Options
13.5. Output Options
13.6. Build Options
13.7. General Targets
14. Survey of Additional Capabilities
III. Advanced Functionality
15. The Abuild.conf File
15.1. Abuild.conf Syntax
16. The Abuild.backing File
17. The Abuild Interface System
17.1. Abuild Interface Functionality Overview
17.2. Abuild.interface Syntactic Details
17.3. Abuild Interface Conditional Functions
17.4. Abuild.interface and Target Types
17.5. Predefined Abuild.interface Variables
17.5.1. Interface Variables Available to All Items
17.5.2. Interface Variables for Object-Code Items
17.5.3. Interface Variables for Java Items
17.6. Debugging Interface Issues
18. The GNU Make backend
18.1. General Abuild.mk Syntax
18.2. Make Rules
18.2.1. C and C++: ccxx Rules
18.2.2. Options for the msvc Compiler
18.2.3. Autoconf: autoconf Rules
18.2.4. Do Nothing: empty Rules
18.3. Autoconf Example
19. The Groovy Backend
19.1. A Crash Course in Groovy
19.2. The Abuild.groovy File
19.2.1. Parameter Blocks
19.2.2. Selecting Rules
19.3. Directory Structure for Java Builds
19.4. Class Paths and Class Path Variables
19.5. Basic Java Rules Functionality
19.5.1. Compiling Java Source Code
19.5.2. Building Basic Jar Files
19.5.3. Wrapper Scripts
19.5.4. Testing with JUnit
19.5.5. JAR Signing
19.5.6. WAR Files
19.5.7. High Level Archives
19.5.8. EAR Files
19.6. Advanced Customization of Java Rules
19.7. The Abuild Groovy Environment
19.7.1. The Binding
19.7.2. The Ant Project
19.7.3. Parameters, Interface Variables, and Definitions
19.8. Using QTest With the Groovy Backend
19.9. Groovy Rules
19.10. Additional Information for Rule Authors
19.10.1. Interface to the abuild Object
19.10.2. Using org.abuild.groovy.Util
20. Controlling and Processing Abuild's Output
20.1. Introduction and Terminology
20.2. Output Modes
20.3. Output Prefixes
20.4. Parsing Output
20.5. Caveats and Subtleties of Output Capture
21. Shared Libraries
21.1. Building Shared Libraries
21.2. Shared Library Example
22. Build Item Rules and Automatically Generated Code
22.1. Build Item Rules
22.2. Code Generator Example for Make
22.3. Code Generator Example for Groovy
22.4. Multiple Wrapper Scripts
22.5. Dependency on a Make Variable
22.6. Caching Generated Files
22.6.1. Caching Generated Files Example
23. Interface Flags
23.1. Interface Flags Conceptual Overview
23.2. Using Interface Flags
23.3. Private Interface Example
24. Cross-Platform Support
24.1. Platform Selection
24.2. Dependencies and Platform Compatibility
24.3. Explicit Cross-Platform Dependencies
24.3.1. Interface Errors
24.4. Dependencies and Pass-through Build Items
24.5. Cross-Platform Dependency Example
25. Build Item Visibility
25.1. Increasing a Build Item's Visibility
25.2. Mixed Classification Example
26. Linking With Whole Libraries
26.1. Whole Library Example
27. Opaque Wrappers
27.1. Opaque Wrapper Example
28. Optional Dependencies
28.1. Using Optional Dependencies
28.2. Optional Dependencies Example
29. Enhancing Abuild with Plugins
29.1. Plugin Functionality
29.2. Global Plugins
29.3. Adding Platform Types and Platforms
29.3.1. Adding Platform Types
29.3.2. Adding Platforms
29.4. Adding Toolchains
29.5. Plugin Examples
29.5.1. Plugins with Rules and Interfaces
29.5.2. Adding Backend Code
29.5.3. Platforms and Platform Type Plugins
29.5.4. Plugins and Tree Dependencies
29.5.5. Native Compiler Plugins
29.5.6. Checking Project-Specific Rules
29.5.7. Install Target
30. Best Practices
30.1. Guidelines for Extension Authors
30.2. Guidelines for Make Rule Authors
30.3. Guidelines for Groovy Target Authors
30.4. Platform-Dependent Files in Non-object-code Build Items
30.5. Hidden Dependencies
30.6. Interfaces and Implementations
31. Monitored Mode
32. Sample XSL-T Scripts
33. Abuild Internals
33.1. Avoiding Recursive Make
33.2. Starting Abuild in an Output Directory
33.3. Traversal Details
33.4. Compatibility Framework
33.5. Construction of the Build Set
33.6. Construction of the Build Graph
33.6.1. Validation
33.6.2. Construction
33.6.3. Implications
33.7. Implementation of the Abuild Interface System
33.8. Loading Abuild Interfaces
33.9. Parameter Block Implementation
IV. Appendices
A. Release Notes
B. Major Changes from Version 1.0 to Version 1.1
B.1. Non-compatible Changes
B.2. Deprecated Features
B.3. Small, Localized Changes
B.4. Groovy-based Backend for Java Builds
B.5. Redesigned Build Tree Structure
C. Upgrading from 1.0 to Version 1.1
C.1. Upgrade Strategy
C.2. Potential Upgrade Problems: Things to Watch Out For
C.3. Upgrade Procedures
C.3.1. High-level Summary of Upgrade Process
C.3.2. Editing abuild.upgrade-data
D. Known Limitations
E. Online Help Files
E.1. abuild --help groovy
E.2. abuild --help helpfiles
E.3. abuild --help make
E.4. abuild --help usage
E.5. abuild --help vars
E.6. abuild --help rules rule:empty
E.7. abuild --help rules rule:groovy
E.8. abuild --help rules rule:java
E.9. abuild --help rules rule:autoconf
E.10. abuild --help rules rule:ccxx
E.11. abuild --help rules toolchain:gcc
E.12. abuild --help rules toolchain:mingw
E.13. abuild --help rules toolchain:msvc
E.14. abuild --help rules toolchain:unix_compiler
F. --dump-data Format
G. --dump-interfaces Format
H. --dump-build-graph Format
I. The ccxx.mk File
J. The java.groovy and groovy.groovy Files
K. The Deprecated XML-based Ant Backend
K.1. The Abuild-ant.properties File
K.2. Directory Structure For Java Builds
K.3. Ant Hooks
K.4. JAR-like Archives
K.5. WAR Files
K.6. EAR Files
L. List of Examples
Index

List of Figures

6.1. Build Item Scopes
7.1. Top-Level Abuild.conf
7.2. Build Trees in general/reference
11.1. Shadowed Dependency
11.2. Build Trees in general/task
11.3. Build Trees in general/user
23.1. Private Interface Flag
24.1. Multiplatform Pass-through Build Item
25.1. Build Item Visibility
30.1. Hidden Circular Dependency
30.2. Shared Include Directory
30.3. Separate Include Directories

List of Tables

5.1. Built-in Platforms, Platform Types, and Target Types
19.1. Default Java Directory Structure
   Next
   Notes For Users of Abuild Version 1.0