Abuild Users' Manual
   Next

Abuild Users' Manual

For Abuild Version 1.0.1, May 29, 2008

Jay Berkenbilt

Copyright © 2007, 2008 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

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. Special Types of Build Items
4.5. 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. External Build Trees
7.1. Using External Build Trees
7.2. External Build Tree Example
8. Telling Abuild What to Build
8.1. Build Targets
8.2. Build Sets
8.2.1. Example Build Set Invocations
8.3. Traits
8.3.1. Declaring Traits
8.3.2. Specifying Traits at Build Time
8.3.3. Example Trait Invocations
8.3.4. Target Selection
8.4. Build Set and Trait Examples
8.4.1. Common Code Area
8.4.2. External Build Tree Example: Project Code Area
8.4.3. Trait Example
8.4.4. Derived Project Example
9. Integration with Automated Test Frameworks
9.1. Test Targets
9.2. Integration with QTest
9.3. Integration with JUnit
10. Backing Areas
10.1. Setting Up Backing Areas
10.2. Resolving Build Items to Backing Areas
10.3. Resolving Externals to Backing Areas
10.4. Integrity Checks
10.5. Comparison of Backing Areas and Externals
10.6. Task Branch Example
10.7. Deleted Build Item
11. Command-Line Reference
11.1. Basic Invocation
11.2. Informational Options
11.3. Control Options
11.4. Build Options
11.5. General Targets
11.6. Java-specific Targets
12. Survey of Additional Capabilities
III. Advanced Functionality
13. The Abuild.conf File
13.1. Abuild.conf Syntax
14. The Abuild Interface System
14.1. Abuild Interface Functionality Overview
14.2. Abuild.interface Syntactic Details
14.3. Abuild Interface Conditional Functions
14.4. Abuild.interface and Target Types
14.5. Predefined Abuild.interface Variables
14.5.1. Interface Variables Available to All Items
14.5.2. Interface Variables for Object-Code Items
14.5.3. Interface Variables for Java Items
15. The Abuild.mk File
15.1. General Abuild.mk Syntax
15.2. Make Rule-specific Targets
15.2.1. C and C++: ccxx Rules
15.2.2. Autoconf: autoconf Rules
15.2.3. Do Nothing: empty Rules
15.3. Autoconf Example
16. The Apache Ant Build Files
16.1. The Abuild-ant.properties File
16.2. Directory Structure For Java Builds
16.3. The Abuild-ant.xml File
17. Shared Libraries
17.1. Building Shared Libraries
17.2. Shared Library Example
18. Automatically Generated Code for GNU Make-based Builds
18.1. Build Item Rules
18.2. Code Generator Example
18.3. Dependency on a Make Variable
19. Java Hooks and Code Generators
19.1. Ant Hooks
19.2. Java Code Generator Example
19.3. Build.xml-driven Java Example
20. Interface Flags
20.1. Interface Flags Conceptual Overview
20.2. Using Interface Flags
20.3. Private Interface Example
21. Cross-Platform Support
21.1. Platform Selection
21.2. Cross-Platform Dependencies
21.3. Cross-Platform Dependency Example
22. Build Item Visibility
22.1. Increasing a Build Item's Visibility
22.2. Mixed Classification Example
23. JARs and Other Archives
23.1. JAR-like Archives
23.2. WAR Files
23.3. EAR Files
24. Linking With Whole Libraries
24.1. Whole Library Example
25. Opaque Wrappers
25.1. Opaque Wrapper Example
26. Enhancing Abuild with Plugins
26.1. Plugin Functionality
26.2. Adding Platform Types and Platforms
26.2.1. Adding Platform Types
26.2.2. Adding Platforms
26.3. Adding Toolchains
26.4. Plugin Examples
26.4.1. Plugins with Rules and Interfaces
26.4.2. Adding Backend Code
26.4.3. Platforms and Platform Type Plugins
26.4.4. Plugins and Externals
26.4.5. Native Compiler Plugins
26.4.6. Checking Project-Specific Rules
26.4.7. Install Target
27. Best Practices
27.1. Guidelines for Extension Authors
27.2. Guidelines for Make Rule Authors
27.3. Guidelines for Ant Target Authors
27.4. Hidden Dependencies
27.5. Interfaces and Implementations
28. Monitored Mode
29. Abuild Internals
29.1. Avoiding Recursive Make
29.2. Starting Abuild in an Output Directory
29.3. Traversal Details
29.4. Computing Valid Traits
29.5. Construction of the Build Set
29.6. Construction of the Build Graph
29.6.1. Validation
29.6.2. Construction
29.6.3. Implications
29.7. Implementation of the Abuild Interface System
29.8. Loading Abuild Interfaces
IV. Appendices
A. Release Notes
B. Known Limitations
C. --dump-data Format
D. The ccxx.mk File
E. List of Examples
Index

List of Figures

6.1. Build Item Scopes
7.1. Build Trees in general/reference
10.1. External Resolved in a Backing Area
10.2. External with Separate Backing Area
10.3. Shadowed Dependency
10.4. Build Trees in general/task
10.5. Build Trees in general/user
20.1. Private Interface Flag
21.1. Multiplatform Pass-through Build Item
22.1. Build Item Visibility
27.1. Hidden Circular Dependency
27.2. Shared Include Directory
27.3. Separate Include Directories
29.1. Multiple Paths to a Build Item

List of Tables

5.1. Built-in Platforms, Platform Types, and Target Types
   Next
   How to Read This Manual