Package Management with Protobuild¶
Protobuild provides a powerful, cross-platform package management system. It is intended to fix some of the shortcomings of NuGet, while also providing greater flexibility for developers.
Primarily the features of Protobuild’s package management system over NuGet are:
- Full support for cross-platform projects, in particular those that need to make native calls (such as P/Invoke).
- Automatic fallback to source code repositories if binary versions are not available for the platform.
- The ability to swap source and binary versions of packages, reducing the work required to diagnose issues in a package’s functionality.
- Packages are LZMA compressed and deduplicated to significantly reduce their size.
- Support for module templates as packages.
Finding packages¶
The primary package repository is located on the Protobuild website. This is known as the Protobuild Package Index.
You can use the search functionality on the Protobuild Package Index to find packages to install. The Protobuild Package Index also instructs you on what command to run to add packages.
Adding packages¶
You can add a package with the following command:
$ Protobuild.exe --add <URI>
For example, to add the MonoGame package to your module, you can use the following command:
$ Protobuild.exe --add http://protobuild.org/MonoGame/MonoGame
Tip
You’ll notice that when adding MonoGame that Protobuild will clone the MonoGame Git repository. This is because (as of the time of writing), MonoGame does not ship binary Protobuild packages.
Packages can ship binary or source versions, or both. By default, when a binary version is not available for the desired platform, Protobuild will automatically fall back to cloning the source repository (if the package has one).
Note
Protobuild will automatically add the folder containing the package to your
.gitignore
file, if your module is being tracked in a Git repository.
If you want to add a package using a specific branch, you can use the following command:
$ Protobuild.exe --add http://protobuild.org/MonoGame/MonoGame@develop
If you want to add a package using a specific Git commit, you can use:
$ Protobuild.exe --add http://protobuild.org/MonoGame/MonoGame@81bdf42b88acd5e859d856bc0f7fa18004ff977e
Switching a package to source format¶
If you have added a package, and it’s currently in binary format, you can get Protobuild to switch the package to a source format with:
$ Protobuild.exe --swap-to-source <URI>
The URI is the URI of the package. If you don’t remember it, you can view
Build\Module.xml
, which contains all of the packages added to your
module, and their URIs.
Note
This will only work if the package has a Git repository URL configured.
Switching a package to binary format¶
If you have added a package, and it’s currently in source format, you can get Protobuild to switch the package to a binary format with:
$ Protobuild.exe --swap-to-binary <URI>
The URI is the URI of the package. If you don’t remember it, you can view
Build\Module.xml
, which contains all of the packages added to your
module, and their URIs.
Note
This will only work if there is a binary version of the package available for the desired commit and platform.
Upgrading a package¶
If you have added a package which is tracking a branch (the default), then you
can upgrade a package to the latest version of that branch by using the
--upgrade
option, like so:
$ Protobuild.exe --upgrade <URI>
By default packages usually track the master
branch of a package. If the
package is in binary format, and you want to upgrade a specific platform, you
can do so with:
$ Protobuild.exe --upgrade <URI> <platform>
Warning
If the package is in source format, this command will undo any local modifications you have made. It works by deleting the package’s folder and replacing it with a newer version.
Note
You will need to run Protobuild with --generate
to generate projects
in the upgraded packages.
Upgrading all packages¶
You can upgrade all packages in a module like so:
$ Protobuild.exe --upgrade-all
If you want to upgrade packages for a specific platform, you can do so with:
$ Protobuild.exe --upgrade-all <platform>
Warning
This command will undo local modifications to any packages that are in source format. It works by deleting all package folders and replacing them with the latest versions.
Note
You will need to run Protobuild with --generate
to generate projects
in the upgraded packages.
Redirecting package URLs¶
You can redirect package URLs for packages to use alternate or modified versions. You can configure package URL redirections at a user level, or transiently with command arguments.
To redirect a package URL for a single invocation of Protobuild, use the
--redirect
option like so:
$ Protobuild.exe --redirect http://source/path http://target/newpath
Most often this argument is used in conjunction with either --generate
or
--upgrade-all
:
$ Protobuild.exe --redirect http://source/path http://target/newpath --upgrade-all
You can configure this option at a user level, by creating or modifying
a file called protobuild-redirects.txt
which resides in your Application Data
directory (~/.config/protobuild-redirects.txt
for Linux and Mac OS). The format
of this file looks like:
# This is a comment
http://source/path -> http://target/newpath
Package URLs can also be redirected to a local Git repository residing on your machine. This is useful if you have an internal modified version of a library that you want to use across multiple projects.
To redirect to a local Git repository, specify the target URL as local-git://
followed by the full path to the Git repository:
# On Linux / Mac:
http://source/path -> local-git:///home/user/path/to/repo
# On Windows:
http://source/path -> local-git://C:\Users\user\Documents\path\to\repo
Removing packages¶
At the moment, to remove a package you’ll need to open Build\Module.xml
with a text editor, and remove the section for package you want to remove.
For example, in the module shown below, to remove the Protogame package, you’d remove the highlighted lines.
<?xml version="1.0" encoding="utf-8"?>
<ModuleInfo xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<Name>MyProject</Name>
<DefaultAction>resync</DefaultAction>
<GenerateNuGetRepositories>true</GenerateNuGetRepositories>
<DisableSynchronisation xsi:nil="true" />
<ModuleAssemblies />
<Packages>
<PackageRef>
<Uri>http://protobuild.org/hach-que/Protogame</Uri>
<GitRef>master</GitRef>
<Folder>Protogame</Folder>
</PackageRef>
</Packages>
</ModuleInfo>
You’ll then need to delete the folder that contains the package.
Creating a package¶
If you want to create and publish a package for your own library on the Protobuild index, refer to the Creating Packages for Protobuild documentation.
Using template packages¶
You can use template packages to quickly set up new modules. This is detailed in the Getting Started guide under Start with a template.