Publish in ten minutes

This walks through publishing an ASM/C program built from a GitHub repository, which is the most common case. TI-BASIC takes a shorter path with no repository at all.

1. Create a project

   Sign in to the console and create a project. You are asked for three things:

   • a name, which is what people see;
   • an id, which is the address the program publishes at. It is derived from the name if you leave it alone, and it can never be changed afterwards;
   • a language, which you may also leave undecided and pick later.

   Choose ASM/C.

2. Install the GitHub App

   Open the project's Flight tab and choose Install on GitHub. Pick the account or organisation, and grant it the repository you want built.

   Aerie reaches GitHub through a GitHub App rather than a URL you type in. The app needs read-only Metadata permission and nothing else. Only public repositories are built.

   Why an app, and not a URL

   What the app can see, how the installation is bound to your account, and the single webhook.

   Read on

3. Connect the repository

   Back in the console, pick the repository from the list and, if you want something other than the default, a branch. That creates the source.

   A repository that is private, archived or invisible to the installation is listed but not eligible, and the reason is shown next to it.

4. Write the manifest

   Flight reads a file called .ceagle-flight at the root of your repository. Create it:

   .ceagle-flight

   [program]
   name = "Snake"
   version = "1.0.0"
   summary = "The classic, on your calculator."
   description = """
   Eat the pixels.
   
   Do not eat yourself.
   """
   categories = ["games"]
   tags = ["arcade", "classic"]
   author = "Ada Lovelace"
   
   [build]
   command = "make"
   output = "bin/SNAKE.8xp"
   timeout = "10m"

   The program table is the listing people see on Roost. The build table is how the program is made.

   Manifest reference

   Every key, its default, its limit and what rejects it.

   Read on

5. Check the output path

   output is a path relative to the repository root, and it is the single most common thing to get wrong. It may be a glob, but it has to match exactly one file.

   The CE C toolchain writes bin/NAME.8xp, where NAME comes from the NAME variable in your Makefile. If your Makefile says NAME = SNAKE, then output = "bin/SNAKE.8xp" is right. When in doubt, output = "bin/*.8xp" matches whatever it produced, as long as there is only one.

6. Push

   Commit the manifest and push to the tracked branch. GitHub sends one webhook, Flight starts a build, and the console shows it running.

   If nothing happens, check that build on push is on for the source. With it off, only the build button in the console starts builds.

7. Read the log

   Open the build. A failed build has an error and a log, truncated at 24 KiB. The most common first failures are:

   Error	Usually means
   the repository has no .ceagle-flight file	it is not where the project looks for it, or the branch you pushed is not the tracked branch
   the build produced no matching artifact	output does not match what the build wrote
   the output pattern matched more than one file	narrow the glob
   a compiler error	the build would fail on your machine too, but the container has no network

   Troubleshooting

   Every build error, and what actually causes it.

   Read on

8. Look at it on Roost

   A successful build writes a release. The project page links to it, and the program is immediately downloadable at its address:

   curl -s https://roost.ceagle.cc/api/v1/programs/snake

What happens on every push after this#

Nothing more from you. A push to the tracked branch starts a build, the build reads the manifest as it stands in that commit, and the release it writes carries the version the manifest names.

Publishing a new version is therefore one line in the manifest and a push.

Next#