Skip to content

Native apps

Download Conveyor

macOS

After dragging to your Applications folder open the Conveyor app and click "Add to path" in the UI.

We'll generate, compile and package a C++ app that uses OpenGL to render a pixel shader.

Screenshot of native app

Create a sample project

  • Install CMake and the compiler toolchain (e.g. Visual Studio).
  • Run these commands: 
    conveyor generate cmake com.example.my-project
cd my-project
mkdir build\windows
cd build\windows
cmake ..\..
cmake --build . --config Release --target install
  • Install CMake and Xcode.
  • Run these commands: 
    conveyor generate cmake com.example.my-project
cd my-project
mkdir -p build/mac
cd build/mac
cmake ../..
make install
  • Install CMake and your distro's development tools. You may also need to install extra development libraries. On Ubuntu/Debian, try sudo apt install build-essential libx11-dev xserver-xorg-dev xorg-dev first.
  • Run these commands: 
    conveyor generate cmake com.example.my-project
cd my-project
mkdir -p build/linux
cd build/linux
cmake ../..
make install

GitHub support

If you use a name like io.github.your_username.your_repo your new project will use git, GitHub Releases and GitHub Pages. There's also a GitHub Action Workflow but that won't be configured out of the box.

Edit the config

In this tutorial we'll only build packages for the same OS you're running on, to avoid the need for cross-compilation.

  • Open conveyor.conf and replace the line that says machines = [windows.amd64, linux.amd64.glibc, mac.amd64, mac.aarch64] with machines = windows.amd64
  • Open conveyor.conf and replace the line that says machines = [windows.amd64, linux.amd64.glibc, mac.amd64, mac.aarch64] with machines = mac.amd64 (if on Intel) or machines = mac.aarch64 (if on Apple Silicon).
  • Open conveyor.conf and replace the line that says machines = [windows.amd64, linux.amd64.glibc, mac.amd64, mac.aarch64] with machines = linux.amd64.glibc

Create the unpackaged app

  • Create a self-contained directory and run the app from there:
conveyor run
  • Get the app into the output directory and take a look.
conveyor make app

conveyor make windows-app

One of the following for Intel/Apple Silicon Macs respectively:

conveyor -Kapp.machines=mac.amd64 make mac-app
conveyor -Kapp.machines=mac.aarch64 make mac-app

conveyor make linux-app

Serve the download site

A plain directory can't be installed or updated. Let's fix that by making self-updating packages.

conveyor make site
cd output
npx serve .

It's self-signed, so you'll need to follow the instructions for how to install it. We'll fix that later.

Serving localhost

Above we use npm and the JavaScript serve module as a simple localhost web server. You can use any web server that properly supports HTTP Content-Range requests. Some servers have bugs therefore we recommend using npx serve . even though this isn't a JavaScript project. You can also use Caddyserver by running caddy file-server --browse --listen :3000. In particular don't use the built in Python web server. It won't work correctly for Windows installs.

It's self-signed, so you'll need to follow the instructions for how to install it. We'll fix that later.

Release an update

In another terminal tab:

  • Change the const char *title string in src/main.cpp to something else.
  • Rebuild the binaries using CMake.
  • Edit conveyor.conf and change the version key to 2.
  • Run conveyor make site to regenerate the download site.

Run the program you installed in the previous step. You should see a window appear with a progress bar, the update be applied and the app should then start, all without any user interaction.

This happens because the sample conveyor.conf file is using the app.updates = aggressive key. Learn more about update modes.

Run the program you installed in the previous step. You should see a window appear with a progress bar, the update be applied and the app should then start, all without any user interaction.

This happens because the sample conveyor.conf file is using the app.updates = aggressive key. Learn more about update modes.

If on Debian derived distributions: Run apt-get update; apt-get upgrade to get the newest version of your app. Otherwise, there is no automatic update supported right now, sorry.

Read the config

It looks like this:

app {
  display-name = "My Project"
  fsname = "my-project"
  version = 2
  site.base-url = "localhost:3000"
  rdns-name = "com.example.my-project"

  machines = [windows.amd64, linux.amd64.glibc, mac.amd64, mac.aarch64]

  icons {
    label = "GL"
  }

  mac.inputs = [
    build/mac/installation/bin -> Contents/MacOS
    build/mac/installation/lib -> Contents/Frameworks
  ]

  windows.amd64.inputs = build/windows/installation/bin
  linux.amd64.inputs = build/linux/installation
}

Tip

The conveyor.conf syntax is a superset of JSON designed for humans writing config files. You can write raw JSON if you're ever unsure about syntax. app.foo.bar = 123 is equivalent to app { foo { bar = 123 } }.

The input definitions let us select where the executable and data files should be imported from.

Learn more about inputs

Read CMakeLists.txt

  • Open the CMakeLists.txt file and read the comments.
  • Observe how linker flags are set for each platform to specify rpaths and -headerpad flags.

Change the icon

Conveyor can draw icons for you.

  • Run conveyor make rendered-icons
  • Look in the output directory to find your new icons.

Basic, but functional.

  • Set the app.icons key to this: 
    app {
  icons {
     label = XY
     gradient = blue
  }
}
  • Rerun conveyor make rendered-icons and look at the results again.

The generated icons will be used automatically.

Tip

Icon generation is meant for quick prototypes, internal tools, student projects and other cases where it's just not worth drawing a pretty icon for your app.

Learn more about icons

You can of course also set the icons key to be a list of bitmap image files (e.g. PNGs), or an SVG file.

Upload a real update site

  • Set the app.license key to the name of your software license e.g. Apache 2, GPL-3 etc. Use SPDX codes if you aren't sure what to put here.
  • Upload your project source code to GitHub.
  • In your config set this key: app.vcs-url = "https://github.com/you/your-project". This automatically sets app.site.base-url to point at the latest GitHub Release.
  • Create a Fine Grained Personal Access Token with Read and Write access to your repository Contents.
  • Set the app.site.github.oauth-token key to the value of the token created above.
  • (optional) Set the app.site.github.pages-branch key to gh-pages.
  • Run conveyor make copied-site.

Your installs will update to whatever the latest release is.

You don't have to use GitHub. If you want to upload your site elsewhere make sure app.vcs-url is set to the URL of your source repository and set app.site.base-url to the URL where the generated site will be uploaded to.

When your app.site.base-url key is set to localhost or a domain that ends in .local Conveyor is in testing mode and you can use it for free. Once you set app.site.base-url to a real website you will be asked to pay and granted three license keys. Each key can be used with one site URL. If you want different update channels (e.g. beta, testing) then you'll need to different site URLs and one key for each.

  • Pick a site URL and set app.site.base-url to point to it, e.g. app { site.base-url = "https://downloads.example.com/myapp" }
  • Set the conveyor.billing-email key to the email address we can use to contact you for billing purposes.
  • Run conveyor make site.
  • You'll be asked to visit a payment URL where you can enter credit card data, and the conveyor.license-key key will be set to a short random code. This key is linked to your chosen download site URL.
  • Rerun conveyor make site.

To release an update you just re-upload the files to the site URL.

Learn more about download sites

Signing

Your users must follow annoying instructions to install the app. That's because it's being self-signed, not signed by a recognized certificate authority. Let's fix that.

When you ran your first command Conveyor announced it had generated a "root key" and that you should back it up. The root key is stored in your defaults.conf file and looks like this:

app.signing-key = "little peace follow cave drive pluck pony rebel grant barrel mammal skate devote skate amateur abandon shaft farm relax cousin few initial olive catch/2023-01-27T16:28:23Z"

Backups

  • Make a backup of your root key.

You must always back up your root key, even if you will later import signing keys you already have. The root key is also used for signing Mac update feeds, Linux packages and apt repositories.

It's represented as words so you can write it down with pen and paper for quick and safe offline backups. Remember to include the generation date!

All the different keys you need can be deterministically derived from this one root key.

The cheapest way to release your app to everyone is to join the Apple Developer Programme (about $100/yr) and then sign up for the Microsoft Store (about $19/yr for an individual, a bit more for companies). Conveyor can release via the Store and when you do this Microsoft will sign your software for you. This is cheaper and easier than buying signing certificates.

How to buy new certificates

A certificate request file (CSR) can be uploaded to a certificate authority like Apple, DigiCert or ssl.com to get back a certificate. The certificate links your public key to a verified personal or corporate identity and is included inside the app binaries on Windows and macOS along with the signatures. Conveyor generated two .csr files and printed the paths to them.

  • Log in using an Apple ID to the Apple developer programme. Joining will require a credit card payment.
  • Request a "Developer ID Application" certificate using the Apple Developer console. You can do this with any web browser and operating system, but you must be the account holder.
  • Upload the apple.csr file that was created next to your defaults.conf file when you created your root key above.

You'll get a .cer file back immediately. There is no review or approval process because the verification is linked to your credit card details.

  • Pick a certificate authority that sells Authenticode certificates. DigiCert is a good choice. Please refer to this FAQ section for more information on the difference between normal and EV certificates.
  • Upload the windows.csr file that was created next to your defaults.conf when you created a root key above. You will need to verify your identity with the CA.
  • Download the certificate in a format of your choice. Conveyor understands several but PEM works well.
  • Place your certificate files next to your defaults.conf. Name them apple.cer and windows.cer.
  • Add this to defaults.conf: 
    app {
  mac.certificate = apple.cer
  windows.certificate = windows.cer
}

If you're shipping to macOS you need to configure Apple notarization. Learn how to set up notarization.

  • Run conveyor make site or build unpackaged apps again. Your apps should now be signed and notarized.

Learn more about keys and certificates

Become a 🐢 tortoise

You will probably not be satisfied with the feature set shown in this short tutorial. The rest of the documentation awaits!