README.md 3.71 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.

David Owens II's avatar
David Owens II committed
7
`atbuild` is a cross-platform build system, primarily for Swift-language projects, following the [Anarchy Tools philosophy](http://anarchytools.org/) of simple, unopinionated, hackable tools.
Drew's avatar
Drew committed
8

Drew's avatar
Drew committed
9
# Tasks
Drew's avatar
Drew committed
10

Drew's avatar
Drew committed
11
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
12

Drew's avatar
Drew committed
13
```bash
Drew's avatar
Drew committed
14 15 16
$ atbuild build
$ atbuild build-tests
$ atbuild run-tests
Drew's avatar
Drew committed
17
$ atbuild #runs a task named "default"
Drew's avatar
Drew committed
18 19 20
```


Drew's avatar
Drew committed
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40
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
41 42

```bash
Drew's avatar
Drew committed
43 44 45 46 47 48
$ atbuild run
Building package foo...
Running task run...
Hello world!
Completed task run.
Built package foo.
Drew's avatar
Drew committed
49 50
```

Drew's avatar
Drew committed
51
# Building Swift code
52

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

Drew's avatar
Drew committed
55
```clojure
56
(package
Drew's avatar
Drew committed
57
  :name "foo"
58 59

  ;;These "tasks" are just entrypoints on the CLI.
Drew's avatar
Drew committed
60
  ;;For example, `atbuild build` runs the `build` task.
61
  :tasks {
Drew's avatar
Drew committed
62 63
    :build {
      :tool "atllbuild"
64 65
      :sources ["src/**.swift"] ;;walk the src directory, looking for Swift files
      :output-type "executable"
Drew's avatar
Drew committed
66
      :name "example"
Drew's avatar
Drew committed
67
    }
68 69
  }
)
Drew's avatar
Drew committed
70 71
```

Drew's avatar
Drew committed
72
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
73

Drew's avatar
Drew committed
74 75 76 77
# Options

`atbuild` supports several command-line options:

Drew's avatar
Drew committed
78
* `--use-overlay [overlay]`, which you can read more about in our [overlays](http://anarchytools.org/docs/overlays.html) documentation.
Drew's avatar
Drew committed
79 80 81 82
* `-f [atpkg-file]` which builds a package file other than `build.atpkg`
* `--help`, which displays a usage message
* `--clean`, which forces a clean build
* `--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` uses "xcode 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
83
* `--platform` which specifies the target platform.  By default, this is the current platform.  Pass a different value (`osx` or `linux`) to cross-compile, only if your compiler supports it.
Drew's avatar
Drew committed
84

Drew's avatar
Drew committed
85 86 87 88 89 90 91
# 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
92

Drew's avatar
Drew committed
93 94 95 96 97 98 99 100 101 102 103 104
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
105 106 107 108 109 110 111 112

# 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
113 114 115


*Maintainer note: if you edit this file, edit the one in [this repo](https://github.com/AnarchyTools/anarchytools.github.io) as well.*