Skip to content

Package Definition Reference

Jump to bottom
JustMichael edited this page Jul 26, 2020 · 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+"],
    "compiler": {
      "site": "github.com",
      "user": "sampctl",
      "repo": "compilers",
      "version": "3.10.10"
    }
  },
  "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.

build

This field allows you to specify the compiler options for when you use sampctl package build to compile your code.

For full reference, see the Build Configuration Reference page.

builds

This is just an array of build objects, this allows you to specify multiple build configurations and choose them with sampctl package build <name>

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.

runtimes

This is just an array of runtime objects, this allows you specify multiple runtime configurations and choose one with sampctl package run <name>.

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