-
Notifications
You must be signed in to change notification settings - Fork 33
Dependencies
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.
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:
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
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.
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
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 merge
ing or
rebase
ing to the original.
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: