Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vknabel/Archery
Declare all your project's metadata and what you can do with it in one single place.
https://github.com/vknabel/Archery
archery arrow cli hacktoberfest metadata mint swift swift-package-manager
Last synced: about 2 months ago
JSON representation
Declare all your project's metadata and what you can do with it in one single place.
- Host: GitHub
- URL: https://github.com/vknabel/Archery
- Owner: vknabel
- License: mit
- Created: 2018-01-07T11:36:19.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-08-23T21:40:33.000Z (about 1 year ago)
- Last Synced: 2024-07-20T18:44:39.489Z (2 months ago)
- Topics: archery, arrow, cli, hacktoberfest, metadata, mint, swift, swift-package-manager
- Language: Swift
- Homepage: https://www.vknabel.com/Archery
- Size: 1.07 MB
- Stars: 46
- Watchers: 4
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-system-swift - Archery - line tool to **manage** your projects' **metadata**. (The Index / Developer Tools)
README
# 🏹 Archery
*Archery* allows you to declare all your project's metadata and what you can do with it in one single place.
All fueled with the power of scripting.
Within Archery all your data is either declared as YAML in one file called `Archerfile` or generated by scripts, 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, `loaders` is there to generate additional metadata.
The following code shows how an Archerfile may look like. Besides the name and version of the project, it declares two scripts:
```yaml
name: YourProject
help: Thanks for downloading this project and trying it out.
version: 1.0.0
loaders:
- cat Metadata/*.yml
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 xcproj` will use [Mint](https://github.com/yonaskolb/Mint) to load [vknabel/BashArrow](https://github.com/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-version` is based on [vknabel/StencilArrow](https://github.com/vknabel/StencilArrow). It will pass all contents of the Archerfile to render the contents of `Version.swift.stencil` using the [Stencil](https://github.com/kylef/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.
```bash
$ 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.
## Scripts
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](https://github.com/vknabel/ArrowKit/blob/master/README.md). |
| `version` | `master` | The version that shall be used. Will be cached within `.archery/mint` |
| `help` | None | The description of the script. |
| `nestedArrow` | `false` | Treat subcommands as arrow. Allows to write arrows in different languages. See [vknabel/ArrowKit](https://github.com/vknabel/ArrowKit/blob/master/README.md). |
## Getting Started
In order to use Archery within your own project, either create your Archerfile by hand or let Archery create one for you.
```bash
$ 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 `.podspec`, `Package.swift` and `Cartfile`. All your dependencies would be declared within your Archerfile, the manifests would be generated using [vknabel/StencilArrow](https://github.com/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](https://github.com/vknabel/ArcheryArrow). You can find a more complete list at the [Available Arrows](#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](#available-arrows).
## Installation
### Using Mint
```bash
$ mint run vknabel/Archery
```
### Using Marathon
```bash
$ marathon run vknabel/archery
```
### Swift Package Manager
```bash
$ 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.
## Environment Variables
Archery passes the following environment variables to each script including loaders.
| Name | Description | Example use case |
| -------------------------- | ----------------------------------- | --------------------------------------------- |
| `ARCHERY` | Path to the archery executable. | To run child processes `$ARCHERY script-name` |
| `ARCHERY_METADATA` | JSON contents of all metadata. | Parse metadata in your scripts. |
| `ARCHERY_SCRIPT` | JSON contents of the script config. | Parse config in your scripts. |
| `ARCHERY_API_LEVEL` | Number of the API level. | To improve backwards compatibility. |
| `ARCHERY_LEGACY_MINT_PATH` | Path to the mint driver. | In case your script relies on mint. |
## Available Legacy Arrows
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](https://github.com/vknabel/ArrowKit/blob/master/README.md) and feel free to add to add your own arrow here.
### Archery
[vknabel/ArcheryArrow](https://github.com/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
### Bash
[vknabel/BashArrow](https://github.com/vknabel/BashArrow) Run bash scripts.
* Write custom arrows in other languages using the `"nestedArrow": true`
* Generate your docs using jazzy
### Beak
[vknabel/BeakArrow](https://github.com/vknabel/BeakArrow) Run functions inside Swift files.
*Based on [yonaskolb/Beak](https://github.com/yonaskolb/Beak).*
* Great to keep related programs together
* Automate your project
* Write custom arrows in Swift using `"nestedArrow": true`
### Stencil
[vknabel/StencilArrow](https://github.com/vknabel/StencilArrow) Render your metadata.
*Based on [kylef/Stencil](https://github.com/kylef/Stencil).*
* Keep your versions up-to-date
* Generate your Podfile
* Create new models or classes
### Marathon
[vknabel/MarathonArrow](https://github.com/vknabel/MarathonArrow) Run Swift scripts.
*Based on [JohnSundell/Marathon](https://github.com/JohnSundell/Marathon).*
* Write arrows that are specific to your project with `"nestedArrow": true`
* Automate your project
### Mint
[vknabel/MintArrow](https://github.com/vknabel/MintArrow) Run CLIs written in Swift. Internally used for all arrows.
*Based on [yonaskolb/Mint](https://github.com/yonaskolb/Mint).*
* Run Swiftlint, SwiftFormat and other scripts
* Install local dependencies when needed
## Development Status
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.
## Contributors
* Valentin Knabel, [@vknabel](https://github.com/vknabel), [email protected], [@vknabel](https://twitter.com/vknabel) on Twitter
## License
Archery is available under the [MIT](https://github.com/vknabel/archery/master/LICENSE) license.