Skip to content

Build Configuration Reference

Jump to bottom
Barnaby Keene edited this page Mar 7, 2022 · 5 revisions

A Build Configuration provides a way of setting compiler arguments in JSON form to save you from using a mess of batch scripts or makefiles.

It's not mandatory and if it's missing from a pawn.json and you run sampctl package build, sampctl will choose some default settings based on the standards that the SA:MP community have adopted. This includes:

Here's an example of a build object:

{
  "args": ["-;+", "-(+", "-+", "-d0", "-O1", "-Z+"],
  "includes": ["legacy"],
  "constants": {
    "_DEBUG": "7"
  },
  "compiler": {
    "version": "3.10.10"
  }
}

builds

This means you can specify multiple sets of options. So you could make a live and a dev config for your gamemode and build with either:

  • sampctl package build dev for development, perhaps with -d3, a faster compile time and a lower MAX_PLAYERS
  • sampctl package build live for the public server, without -d3 and all the optimisations active with -O3 
{
  "builds": [
    {
      "name": "dev",
      "args": ["-;+", "-(+", "-d3", "-Z+"],
      "includes": ["./non_github_packages/"],
      "constants": {
        "MAX_PLAYERS": "10"
      }
    },
    {
      "name": "live",
      "args": ["-;+", "-(+", "-O1", "-Z+"],
      "includes": ["./non_github_packages/"],
      "constants": {
        "MAX_PLAYERS": "250"
      }
    }
  ]
}

Below is a description of each field:

version

This allows you to set the compiler version. See the compiler releases page.

name

The name field is used to identify the build config when using sampctl package build. If no build is specified and a package defines multiple build configs, the first one is chosen.

input

If set, will override the entry field in the Package Definition. This allows you to specify different input files for different builds. This does not need to be used in conjunction with output (see below) allowing a single output from multiple different inputs.

output

Similar to input, replaces the output field in the Package Definition. This sets the output file for the build. This does not need to be used in conjunction with input allowing a single input to go to multiple outputs.

workingDir

This path is passed to the compiler's -D flag. You should not need to use this unless you have a very specific directory layout and specific requirements.

args

If args is set, the default is completely ignored so if you just want to add arguments to the defaults, you must manually specify the defaults too.

includes

includes is a list of directories not a list of files. Each item in this list translates directly to a -i flag being passed to the compiler. This is useful if you want to specify a custom dependency that is not available on GitHub but still include it via #include <file> instead of #include "file".

In the example above, there is "./non_github_packages/" which means if you create a folder in your package directory named non_github_packages you can drop .inc files in there that aren't available on GitHub.

constants

constants allows you to pass compile-time constants. These are the same as adding #define SOMETHING to the top of your script. For example, you could have two builds, one that defines MAX_PLAYERS as 1000 and one that defines it as 10 just for development purposes which would speed up build times.

Clone this wiki locally