Abuild Users' Manual
   Next

Abuild Users' Manual

For Abuild Version 1.1.1, March 1, 2010

Jay Berkenbilt

Copyright © 2007-2010 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. Build Options
13.6. 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. Shared Libraries
20.1. Building Shared Libraries
20.2. Shared Library Example
21. Build Item Rules and Automatically Generated Code
21.1. Build Item Rules
21.2. Code Generator Example for Make
21.3. Code Generator Example for Groovy
21.4. Multiple Wrapper Scripts
21.5. Dependency on a Make Variable
21.6. Caching Generated Files
21.6.1. Caching Generated Files Example
22. Interface Flags
22.1. Interface Flags Conceptual Overview
22.2. Using Interface Flags
22.3. Private Interface Example
23. Cross-Platform Support
23.1. Platform Selection
23.2. Cross-Platform Dependencies
23.2.1. Interface Errors
23.3. Cross-Platform Dependency Example
24. Build Item Visibility
24.1. Increasing a Build Item's Visibility
24.2. Mixed Classification Example
25. Linking With Whole Libraries
25.1. Whole Library Example
26. Opaque Wrappers
26.1. Opaque Wrapper Example
27. Optional Dependencies
27.1. Using Optional Dependencies
27.2. Optional Dependencies Example
28. Enhancing Abuild with Plugins
28.1. Plugin Functionality
28.2. Global Plugins
28.3. Adding Platform Types and Platforms
28.3.1. Adding Platform Types
28.3.2. Adding Platforms
28.4. Adding Toolchains
28.5. Plugin Examples
28.5.1. Plugins with Rules and Interfaces
28.5.2. Adding Backend Code
28.5.3. Platforms and Platform Type Plugins
28.5.4. Plugins and Tree Dependencies
28.5.5. Native Compiler Plugins
28.5.6. Checking Project-Specific Rules
28.5.7. Install Target
29. Best Practices
29.1. Guidelines for Extension Authors
29.2. Guidelines for Make Rule Authors
29.3. Guidelines for Groovy Target Authors
29.4. Platform-Dependent Files in Non-object-code Build Items
29.5. Hidden Dependencies
29.6. Interfaces and Implementations
30. Monitored Mode
31. Sample XSL-T Scripts
32. Abuild Internals
32.1. Avoiding Recursive Make
32.2. Starting Abuild in an Output Directory
32.3. Traversal Details
32.4. Compatibility Framework
32.5. Construction of the Build Set
32.6. Construction of the Build Graph
32.6.1. Validation
32.6.2. Construction
32.6.3. Implications
32.7. Implementation of the Abuild Interface System
32.8. Loading Abuild Interfaces
32.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 helpfiles
E.2. abuild --help usage
E.3. abuild --help vars
E.4. abuild --help rules rule:empty
E.5. abuild --help rules rule:groovy
E.6. abuild --help rules rule:java
E.7. abuild --help rules rule:autoconf
E.8. abuild --help rules rule:ccxx
E.9. abuild --help rules toolchain:gcc
E.10. abuild --help rules toolchain:mingw
E.11. abuild --help rules toolchain:msvc
E.12. 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
22.1. Private Interface Flag
23.1. Multiplatform Pass-through Build Item
24.1. Build Item Visibility
29.1. Hidden Circular Dependency
29.2. Shared Include Directory
29.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