Skip to content

Package Definition Reference

Jump to bottom
Southclaws edited this page Jun 1, 2018 · 19 revisions

Pawn Packages are described by a JSON file in the root directory, this JSON file looks like this:

{
  "user": "Southclaws", // your GitHub username
  "repo": "samp-afk-detect", // the GitHub project name
  "contributors": [
    "Southclaws", // if others helped with the project, list them here
    "Y_Less"
  ],
  "website": "http://forum.sa-mp.com/showthread.php?t=61241", // if you have a website or forum topic, add it here
  "entry": "test.pwn", // the script that compiles and runs your code
  "output": "test.amx", // the output AMX when the package is built
  "local": true, // run the package locally in the current directory
  "dependencies": [
    "sampctl/samp-stdlib" // other packages this package requires to build properly
  ],
  "dev_dependencies": [
    "pawn-lang/YSI-Includes", // same as above but only for development
    "ScavengeSurvive/test-boilerplate"
  ],
  "build": {
    // this is the compiler configuration section, this is where you can set flags such as -d3 and add new include directories
    "args": ["-d3", "-;+", "-(+", "-Z+"]
  },
  "builds": [
    // you can also define multiple ways of compiling the code here
    // usage: sampctl package build <name>
    {
      "name": "main" // first build is always default
    },
    {
      "name": "unit-tests",
      "constants": {
        "RUN_TESTS": "1" // you can declare constant definitions here
      }
    }
  ],
  "runtime": {
    "mode": "y_testing" // runtime modes are useful for testing
  },
  "runtimes": [
    // you can also define multiple ways of running the package
    // usage: sampctl package run <name>
    {
      "name": "dev",
      "port": 8080
    },
    {
      "name": "prod",
      "port": 7777
    }
  ]
  "include_path": "pawno/include" // if your .inc files aren't in the repository root then declare the path here
}

Below is a section for most of the fields in the above example. There is one field missing from the example: resources which only applies to plugin packages, this is covered on the Plugin Packages page.

user and repo

These fields are simply your GitHub username and the repository name. If you're not releasing the package open source on GitHub then these don't matter.

entry and output

Entry describes the .pwn file required to compile this package and output describes where the compiled .amx file should go once it has been built.

These fields are required and there are two use cases for compiling a package:

The package is a gamemode

In this case, you would usually have your Package Definition in the root of your server directory (next the server files like samp-server.exe or samp03svr) then your entry would be gamemodes/MyGamemodeScript.pwn:

{
  "entry": "gamemodes/MyGameModeScript.pwn",
  "output": "gamemodes/MyGameModeScript.amx"
}

The package is a library

In this case, you don't compile the library directly so don't set the .inc as the entry. Instead, you would create a tests.pwn or similar and then include your library into that file for unit testing or in-game testing.

{
  "entry": "test.pwn",
  "output": "test.amx"
}

For more information on writing packages, see the Packages page.

local

This field was introduced in 1.8 and provides a much easier way to run servers. The default value is false which is fine for developing libraries.

When local is set to true, the package will be run in the package directory instead of in a temporary runtime area in ~/.samp/runtimes.

What this means is, when you run sampctl package run, the samp-server.exe/samp03svr files (and all their friends) will be put in the same directory as the pawn.json file and executed there.

This is designed for servers/gamemodes - this is a standard folder layout for hosting a SA:MP server.

Note: This feature acts as a replacement to the samp.json file and the sampctl server * commands. If you previously used this file and these commands to manage your server, read this page to update your configuration.

dependencies

This is where you list all the other packages that your script needs to compile.

Important: Dependencies do not need a pawn.json/pawn.yaml file in their repository to classify as a "Pawn Package" - it just helps a lot when sampctl is figuring out all the dependencies of a package.

A "dependency" is a User/Repo string and describes a GitHub repository. The SA:MP community has widely adopted GitHub as the location for uploading and maintaining gamemodes, includes and filterscripts so that's why sampctl uses it for package management.

Here is an example of a dependencies field for a simple package: (the entry and output fields, though required, have been ignored in this example)

{
  "dependencies": ["sampctl/samp-stdlib", "oscar-broman/md-sort"]
}

This package depends on samp-stdlib maintained by Southclaws and the md-sort library maintained by oscar-broman.

samp-stdlib is a special library that almost all Packages will need to depend on. It's the "SA:MP Standard Library" and simply contains all the .inc files that ship with the server - this includes files like a_samp.inc etc. The repository is maintained by @Southclaws and will be updated for each SA:MP server release.

For more information on dependencies, please read the Dependencies page.

dev_dependencies

This field is the same format as dependencies. This field is used for declaring dependencies for a package that are only used during development of the package itself.

Any dependencies here are not necessary to include the package in another package.

For example, this package depends on samp-stdlib and also depends on YSI but as a dev dependency:

{
  "dependencies": ["sampctl/samp-stdlib"],
  "dev_dependencies": ["pawn-lang/YSI-Includes"]
}

So if you run sampctl package ensure inside this package directly, you would pull samp-stdlib and YSI-Includes.

However, if you uploaded the above package to github and named it my-package then create another package:

{
  "dependencies": ["Southclaws/my-package"]
}

Then if you run sampctl package ensure inside this package directly, you would pull samp-stdlib but not YSI-Includes because YSI is only a development dependency of my-package and because of that, it's not required to use the package, only to run/test it.

builds

This section allows you to specify the compiler options for the package. 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:

The builds field is an array of configurations which 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": ["-;+", "-(+", "-O3", "-Z+"],
      "includes": ["./non_github_packages/"],
      "constants": {
        "MAX_PLAYERS": "250"
      }
    }
  ]
}

Below is a description of each field:

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.

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.

runtime

This field allows you to configure how the package is run when you use sampctl package run. This is effectively your server.cfg but in beautiful JSON format.

For full reference, see the Runtime Configuration Reference page.

This is mainly used for configuring a server but can also be used for tweaking package tests.

include_path

It's common with plugins to place the Pawn .inc file into a subdirectory. If this is the case with your library, you must specify the additional path here.

For example, urShadow/Pawn.RakNet has the include file in src/ so the package definition must contain this:

{
  "include_path": "src"
}
Clone this wiki locally