Archery allows you to declare all your project's metadata and what you can do with it in one single place.
Within Archery all your data is centralized as YAML in one file called
Archerfile, which will be passed to arrows as JSON. The whole content of that file is treated as metadata. Within
scripts you declare whatever you want to run.
The following code shows how an Archerfile may look like. Besides the name and version of the project, it declares two scripts:
name: YourProject help: Thanks for downloading this project and trying it out. version: 1.0.0 scripts: xcproj: swift package generate-xcodeproj generate-version: arrow: vknabel/StencilArrow help: Injects the current version into the SPM project template: Version.swift.stencil destination: Sources/ArcheryKit/Version.generated.swift searchPaths: [Scripts]
$ archery xcprojwill use Mint to load vknabel/BashArrow, which executes a given command. Whenever you want to run simple scripts on the command line which do not require global installs, this is an universal way to go.
$ archery generate-versionis based on vknabel/StencilArrow. It will pass all contents of the Archerfile to render the contents of
Version.swift.stencilusing the Stencil language. Whenever you need information of your Archerfile inside other files, this way should be the most convenient.
If you are new to a project, Archery will help you to get started as it acts as a project internal CLI. The generated help for the Archerfile can be accessed as below.
$ archery Thanks for downloading this project and trying it out. Available Commands: generate-version Injects the current version into the SPM project xcproj Generate the Xcode Project for the current SwiftPM project
No matter which arrow you will choose for your scripts: it comes with all dependencies it needs. No need for any additional commands.
The script tag at root level drives the available subcommands and is interpreted as Array of scripts.
| Option | Default | Description |
arrow | Required | Github repository for a Swift CLI. See vknabel/ArrowKit. |
master | The version that shall be used. Will be cached within
help | None | The description of the script. |
false | Treat subcommands as arrow. Allows to write arrows in different languages. See vknabel/ArrowKit. |
In order to use Archery within your own project, either create your Archerfile by hand or let Archery create one for you.
$ archery init 🏹 Created at Archerfile
Now you can add all your metadata and scripts. Don't know where to start? Here are some examples for you:
- If you develop a library you could generate your
Cartfile. All your dependencies would be declared within your Archerfile, the manifests would be generated using vknabel/StencilArrow.
- What is your release process? Why not start it using
$ archery release? As this script will be more complex, the best would be to use vknabel/ArcheryArrow. You can find a more complete list at the Available Arrows.
- What do you need to install or configure in order to get started with your project? You could move some dependencies into arrows or guide the new users through a tutorial. You can find a more complete list at the Available Arrows.
$ mint run vknabel/Archery
$ marathon run vknabel/archery
Swift Package Manager
$ git clone https://github.com/vknabel/Archery.git $ cd Archery $ swift build -c release $ cp -f .build/release/archery /usr/local/bin/archery
Archery can also be embedded within your own CLI using SwiftPM.
Currently the following arrows are known. Feel free to add your own arrows. If you want to write your own arrow head over to vknabel/ArrowKit and feel free to add to add your own arrow here.
vknabel/ArcheryArrow Runs multiple scripts.
- Automate complex actions by reusing small building blocks
- Combine all steps for a new release into one command
- Enforce code style and code format in a pre-commit hook
vknabel/BashArrow Run bash scripts.
- Write custom arrows in other languages using the
- Generate your docs using jazzy
- Great to keep related programs together
- Automate your project
- Write custom arrows in Swift using
- Keep your versions up-to-date
- Generate your Podfile
- Create new models or classes
- Write arrows that are specific to your project with
- Automate your project
- Run Swiftlint, SwiftFormat and other scripts
- Install local dependencies when needed
As Archery is still in early development I want every user to know as early as possible what may actually change or break in future. This project uses semantic versioning. Version 1.0.0 will be released when known bugs are fixed, all major features have been implemented and upcoming one can be implemented without breaking changes. Additional requirements are a good documentation and good error messages. Until 1.0 has been reached minor updates may break, but patches will stay patches and hence safe for updates.
In bigger projects the
Archerfile may get huge when used regularly. Later it shall be possible to extract some JSON values into external files and even other scripts. As the
Archerfile should not be read directly, this update won’t break arrows.
Archery is available under the MIT license.
Help us keep the lights on
0.2.1 - Jun 21, 2018
- Bumped internal dependencies
- Correctly passes interrupts
- Shorthand arrow syntax will be migrated to
Upcoming Breaking Change
Currently when passing a named string as a script, it will be expanded as
The new behavior will run the provided string as a command line script as
arrow: BashArrow and
command: your script.
Until the next breaking update, repo names will still work as previously.
All strings containing exactly one
/, no space and which do not start with a
., will still be treated as arrow.
scripts: # Deprecated shorthand example: "vknabel/BeakArrow" # this would run the arrow # New behavior format: "swiftformat ." # this would run a `vknabel/BashArrow` command
0.2.0 - Apr 5, 2018
Archerfile supports YAML
Especially if your Archerfile contains descriptions it will get hard to read soon. As a better format we replaced JSON with YAML, which is a superset of JSON and hence won’t break your configs. As the Archerfile should not be read directly, this update won’t break arrows.
0.1.1 - Jan 24, 2018
- Improved error messages
- Improved README.md