Dependencies

Package Locators

A package locator is a string to indicate to sampctl where a package is located.

You can either use user/repo format which defaults to GitHub and is perfect for open source projects:

• ScavengeSurvive/velocity (https://github.com/ScavengeSurvive/velocity)

Or you can supply a full SSH URL for private repositories:

• git@gitlab.com:JamesBond/SuperSecretPrivatePawnCode.git

Note that you must have an SSH agent set up for this. Pageant works great on Windows. HTTP Basic Auth for non-SSH repositories will be added in the future if there is significant demand.

Versioning

There have been times in the past where a specific library has breaking changes in certain releases. The best examples of this are the MySQL plugin and the Streamer plugin.

This means you want to "pin" your dependencies to a specific version.

sampctl offers three methods for doing this:

Tag-Based Versioning

This is the most common method of versioning software. This uses the : suffix.

For this example, we'll use the Streamer plugin. Some time in 2017 a version of the Streamer introduced a bug (documented here) that resulted in a few versions being unstable. A lot of users preferred to stay with version 2.8.2 until that bug was found and fixed.

Luckily, the Streamer plugin is a well managed repository with proper GitHub releases!

The version control features of sampctl directly help with this sort of thing. sampctl prefers the use of Semantic Versioning, which you can read more about here.

Here are some examples of a versioned dependency:

• samp-incognito/samp-streamer-plugin:2.8.2 use 2.8.2 and ONLY 2.8.2, not 2.8.3 or anything else
• samp-incognito/samp-streamer-plugin:^2.8.0 use latest version >= 2.8.0, < 2.9.0
• samp-incognito/samp-streamer-plugin:2.9.x use latest 2.9 version (2.9.2 at the time of writing)

You can read more about the versioning syntax here: https://github.com/Masterminds/semver#basic-comparisons

Branches

If you want to force a dependency to use a specific branch (such as YSI's 5.x branch) you can use the @ suffix:

• pawn-lang/YSI-Includes@5.x

Each time you run sampctl package ensure the latest code on that branch will be pulled. This method isn't recommended for live gamemodes as you could pull breaking changes into your project.

Specific Commit

If you need to be really specific about which version you need, you can specify an individual commit with the # suffix followed by the SHA1 hash of the commit:

• pawn-lang/YSI-Includes#938c6f29c4d936a6086060228e963703bd903ea6

Dependency Tree

A package can depend on another package that also depends on packages. When you run sampctl pacakage ensure it will automatically get all the packages required for all dependencies and their dependencies. It does this to simplify the process of getting dependencies and make your job as a library developer or gamemode developer easier.

For example, if your gamemode doesn't use YSI at all but you're using a library that does, you don't need to explicitly add pawn-lang/YSI-Includes to your Package Definition file, as long as the library you're using (the one that needs YSI) has an up-to-date Package Definition that defines pawn-lang/YSI-Includes as a dependency.

When you run sampctl package ensure, it downloads everything to a folder named dependencies, you can open up this folder to check out what has been downloaded. But don't modify anything in here. If you need to modify a library, submit a pull request to be reviewed by the maintainer.

If the maintainer is inactive and you need to make changes, simply fork the project on GitHub, make your changes and then change their username in the dependency string to your own username. Be careful of creating too many forks though, it's always good to keep one copy of a library for everyone to use instead of diverging lots of small changes to many different accounts - this makes keeping updated difficult as you will need to keep mergeing or rebaseing to the original.

Viewing Dependency Trees

If you want to visualise the dependency tree of a package, you can do so on the packages.sampctl.com site by either searching for a package or appending the user/repo package locator string to the URL.

Example from packages.sampctl.com/ScavengeSurvive/mentions: