README.md 3.16 KB
Newer Older
Drew's avatar
Drew committed
1 2 3 4
# atbuild

The Anarchy Tools Build Tool.

Drew's avatar
Drew committed
5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
# Building

To build atbuild "from scratch", simply `./bootstrap.sh`.

Then you can check the program was built successfully:

```bash
$ ./atbuild --help
atbuild - Anarchy Tools Build Tool 0.1.0-dev
https://github.com/AnarchyTools
© 2016 Anarchy Tools Contributors.

Usage:
atbuild [task]
    task: ["default", "helloworld", "bootstrap"]
```

# Configuration

Drew's avatar
Drew committed
24
```bash
Drew's avatar
Drew committed
25
$ atbuild
Drew's avatar
Drew committed
26 27 28
$ atbuild build
$ atbuild build-tests
$ atbuild run-tests
Drew's avatar
Drew committed
29 30
```

Drew's avatar
Drew committed
31
The configuration file defines *tasks*, which are entrypoints on the CLI.  If no task is specified, we run a task called `default`.
Drew's avatar
Drew committed
32

Drew's avatar
Drew committed
33
Configurations [are unsupported](https://github.com/AnarchyTools/atbuild/issues/2) but could look like this:
Drew's avatar
Drew committed
34 35

```bash
Drew's avatar
Drew committed
36
$ atbuild run-tests --platform linux
Drew's avatar
Drew committed
37 38
```

Drew's avatar
Drew committed
39 40
A complete atbuild.yaml example is below.

Drew's avatar
Drew committed
41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67
```yaml
package:
  name: "sample"
  description: "A configuration sample"
  
  # Dependencies aren't resolved by the build tool (you want the package manager), but they look like this:
  
  dependencies:
    - "https://github.com/apple/swift-lldb", “2.2-SNAPSHOT”
    
  # We can declare custom tools.
  tools:
    xctest-runner:
      type: shell
      profiles:
        #specify custom behavior for osx/linux
        platform:
          osx:
            script: "xctest $outputdir/$testlib"
          linux:
            script: "xctest-linux $outputdir/$testlib"
  
tasks:
  
  #There's no magic; this is just a task called "build"
	build:
	  #A tool that compiles the swift module
68
		tool: atllbuild
Drew's avatar
Drew committed
69 70 71 72 73 74 75 76 77 78 79
		
		#The rest of these settings are just options for that tool
		name: json-swift
		output-type: library
		
		#walk the src directory and recursively find all swift files
		source: ["src/**.swift"] 
		profiles:
		  #override custom settings for swift/linux
      platform:
			  linux:
80
				  dependency: ["build-foundation"]
Drew's avatar
Drew committed
81 82 83 84 85 86 87 88 89 90
				  linkflags: ["-lFoundation"]
			  osx:
				  linkflags: ["-Framework Foundation"]
			  default:
				  tool: "abort"
				  message = "You need to specify --profile [osx|linux]"
		
		#A second task, named "build-test"
		#This builds a test target
		build-test:
91
		  dependency: ["build"] #Build the main target first
Drew's avatar
Drew committed
92 93 94 95 96 97 98
		  tool: "lldb-build"
		  name: "test"
		  output-type: "XCTest"
		  source: ["tests/**.swift"]
		
		#A third task, that runs the test
		run-tests:
99
		  dependency: ["build-test"] #build them first
Drew's avatar
Drew committed
100 101 102 103 104 105 106 107
		  tool: xctest-runner #use the xctest-runner tool we created
		  testlib: tests.xctest #pass this argument
```

In the example above, there are three built-in tools: “lldb-build”, "abort", and “shell”. These tools take in the parameters from the configuration file for their respective usages. In addition, there is another tool defined, “xctest-runner”, that is just an alias of sorts to invoke the “shell” tool in a specific way.

The package file is a set of metadata to describe how the build process should work, and push all the actual work out to separate tools. There are a set of tools that are built-in that provide some of the standard behavior we want to support. At the same time, there are extension points to defining new tools as well. These tools can be defined within the package file or within source code for more advanced tools.