README.md 5.13 KB
Newer Older
Drew's avatar
Drew committed
1 2
# atbuild

Drew's avatar
Drew committed
3 4
[![Anarchy Tools compatible](https://img.shields.io/badge/Anarchy%20Tools-compatible-4BC51D.svg?style=flat)](http://anarchytools.org)

Drew's avatar
Drew committed
5 6
The Anarchy Tools Build Tool.

Drew's avatar
Drew committed
7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35
atbuild is a small, configurable, mature, and boring Swift buildsystem.

1.  It just builds your code.  That's it.  No bells, whistles, file downloads, or feature creep.
2.  It is extensible and can be easily customized to work how *you* want.
3.  It has no magic.  It doesn't guess.  It does what you tell it to do.
4.  It has no opinions.  It does not look down on you for writing code "wrong".
5.  It is used to build many large production projects.

It follows the [Anarchy Tools philosophy](https://github.com/AnarchyTools/anarchytools.github.io) of simple, unopinionated, hackable tools.

Key atbuild features:

* Builds Swift 2 & Swift 3 projects
* Can even build with Xcode's Swift
* Builds projects for OSX, Linux, and iOS (experimental)
* Can run custom scripts before, after, and during builds
* Customize all compile and link flags
* Powerful imports system for managing dependencies
* Overlays, custom tools, and external scripts allow maximum customization
* Uses the next-generation `swift-llbuild` engine
* Extensive [documentation](http://anarchytools.org)
* It's 1.0!

atbuild pairs well with:

* [atpm](https://github.com/AnarchyTools/atpm), the Anarchy Tools Package Manager
* [xcode-emit](https://github.com/AnarchyTools/xcode-emit) which emits Xcode projects from an atbuild configuration
* [SublimeAnarchy](https://github.com/AnarchyTools/SublimeAnarchy), the Swift IDE for Sublime Text 3
* Many [other AnarchyTools projects](https://github.com/AnarchyTools)!
Drew's avatar
Drew committed
36

Drew's avatar
Drew committed
37
# Tasks
Drew's avatar
Drew committed
38

Drew's avatar
Drew committed
39
With `atbuild` you define a set of *tasks*, representing high-level operations like building, running, and cleaning.  Then you can use these tasks from the command line.
Drew's avatar
Drew committed
40

Drew's avatar
Drew committed
41
```bash
Drew's avatar
Drew committed
42 43 44
$ atbuild build
$ atbuild build-tests
$ atbuild run-tests
Drew's avatar
Drew committed
45
$ atbuild #runs a task named "default"
Drew's avatar
Drew committed
46 47 48
```


Drew's avatar
Drew committed
49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68
Tasks are defined in a clojure-like format.  Here's a simple example:

```clojure
;; This is a comment

(package
  :name "foo"

  ;;These "tasks" are just entrypoints on the CLI.
  ;;For example, `atbuild build` runs the `build` task.
  :tasks {
    :run {
      :tool "shell"               ;;Tools are functions built into atbuild.
      :script "echo Hello world!" ;;The shell tool requires a script
    }
  }
)
```

Name that `build.atpkg`.  Now we can call 
Drew's avatar
Drew committed
69 70

```bash
Drew's avatar
Drew committed
71 72 73 74 75 76
$ atbuild run
Building package foo...
Running task run...
Hello world!
Completed task run.
Built package foo.
Drew's avatar
Drew committed
77 78
```

Drew's avatar
Drew committed
79
# Building Swift code
80

Drew's avatar
Drew committed
81
How do we build a Swift project?  There's a built-in tool called `atllbuild`, which is our *low-level build system*.
82

Drew's avatar
Drew committed
83
```clojure
84
(package
Drew's avatar
Drew committed
85
  :name "foo"
86 87

  ;;These "tasks" are just entrypoints on the CLI.
Drew's avatar
Drew committed
88
  ;;For example, `atbuild build` runs the `build` task.
89
  :tasks {
Drew's avatar
Drew committed
90 91
    :build {
      :tool "atllbuild"
92 93
      :sources ["src/**.swift"] ;;walk the src directory, looking for Swift files
      :output-type "executable"
Drew's avatar
Drew committed
94
      :name "example"
Drew's avatar
Drew committed
95
    }
96 97
  }
)
Drew's avatar
Drew committed
98 99
```

Drew's avatar
Drew committed
100
That's all you need to get started!  `atbuild` supports many more usecases than can fit in a README.  For more information, browse our [documentation](http://anarchytools.org).
Drew's avatar
Drew committed
101

Drew's avatar
Drew committed
102 103 104 105
# Options

`atbuild` supports several command-line options:

Drew's avatar
Drew committed
106
* `--use-overlay [overlay]`, which you can read more about in our [overlays](http://anarchytools.org/docs/overlays.html) documentation.
Drew's avatar
Drew committed
107 108 109
* `-f [atpkg-file]` which builds a package file other than `build.atpkg`
* `--help`, which displays a usage message
* `--clean`, which forces a clean build
Drew's avatar
Drew committed
110
* `--toolchain` which specifies a nonstandard toolchain (swift installation).  By default we try to guess, but you can override our guess here.  The special string `xcode` or `xcode-beta` uses "xcode (beta) swift" for building.  (Swift 2.2 does not contain all the tools we use, so you need to have a 3.x snapshot installed as well.  However, this is a "mostly" xcode-flavored buildchain.)
Drew's avatar
Drew committed
111
* `--platform` which specifies the target platform.  By default, this is the current platform.  Pass a different value to cross-compile, see [platforms](http://anarchytools.org/docs/platforms.html) for details.
Drew's avatar
Drew committed
112
* `--configuration`, which specifies the active [configuration](http://anarchytools.org/docs/configurations.html)
Drew's avatar
Drew committed
113

Drew's avatar
Drew committed
114 115 116 117 118 119 120
# Building

We publish [binary releases](https://github.com/AnarchyTools/atbuild/releases), which are the easiest way to get started.

`atbuild` is self-hosting, so building it with an existing copy is usually your best bet.

That said, if you're doing something fancy, or are bootstrapping onto a new platform, use `./bootstrap/build.sh`.
Drew's avatar
Drew committed
121

Drew's avatar
Drew committed
122 123 124 125 126 127 128 129 130 131 132 133
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"]
```
Drew's avatar
Drew committed
134 135 136 137 138 139 140 141

# Badges

To declare your project to be compatible with Anarchy Tools, simply

```markdown
[![Anarchy Tools compatible](https://img.shields.io/badge/Anarchy%20Tools-compatible-4BC51D.svg?style=flat)](http://anarchytools.org)
```
Drew's avatar
Drew committed
142 143


Johannes Schriewer's avatar
Johannes Schriewer committed
144 145
*Maintainer note: if you edit this file, edit the one in [this repo](https://github.com/AnarchyTools/anarchytools.github.io) as well.*