This document will show you how to get up and running with Protobuild in 5 minutes. For this guide we’ll assume you’re interested in creating a project.
If instead you’re looking to migrate an existing project, we recommend following this guide to get acquainted with the way that Protobuild works, and then refer to Migrating Existing C# Projects for performing a project migration.
First you’ll need to download Protobuild itself:
After you have downloaded Protobuild, place it in an empty directory where you want to create your project. Protobuild itself is cross-platform; the same executable will run on all desktop platforms.
If you are using source control, you should add or track Protobuild.exe in your source control system. For more information, refer to What files should I keep in source control?
Start with a template¶
Starting with an existing project template is the easiest way to create a new project in Protobuild.
Open a terminal or command prompt, and navigate to the directory where you placed Protobuild. You can start with a new template by running:
$ Protobuild.exe --start http://protobuild.org/commons/Console <name>
<name> with the name you want to give your new project. This will
be the name used when creating the solution file.
If you are running Mac OS X or Linux, you’ll need to prefix the above command
mono (as with all commands in this documentation that execute
This will create a Protobuild module using the template at the specified URL. You can find more templates by searching the Protobuild package index.
Common starting templates (including templates for libraries) can be found under the commons organisation on the Protobuild index.
module means the directory which contains Protobuild.exe, and
all of your project definitions collectively. Protobuild modules can have
submodules, which are subdirectories that contain their own Protobuild
executable and project definitions.
Outside of this Getting Started guide,
project refers to an individual
Protobuild project definition, and not the module as a whole. We just use
project here since it’s familiar to readers.
Start from scratch¶
You can also create an empty Protobuild module if you wish to create project definitions from scratch. To do this, just run the Protobuild executable with no arguments, and it will automatically create the required directories and module configuration.
If you’re creating a module from scratch, you’ll need to refer to the documentation on the various project types and how to create them:
Once you have created your module, you’ll need to generate the C# projects so that you can build your code. To generate the C# projects for your module, run the following command:
$ Protobuild.exe --generate
By default, this will generate C# projects for the current platform you are running Protobuild on.
You can specify what platform you want to generate C# projects for by passing
it as an argument to
--generate. For example, to generate projects for
$ Protobuild.exe --generate Windows
You can also synchronise changes you have made in your C# projects back to the project definition files by running:
$ Protobuild.exe --resync
This is the default command, and is triggered when double-clicking Protobuild under Windows.
This will synchronise and then regenerate the C# projects. If you don’t wish to regenerate the C# projects (to avoid the Visual Studio project reload dialog), you can use the following command instead:
$ Protobuild.exe --sync
If you want to clean up the C# project and solution files generated by Protobuild, you can run the following command:
$ Protobuild.exe --clean
All of the above commands accept a platform as an argument. For more
detail on what commands are available, try
Once you have generated your C# projects, you can build your code in any of
the standard ways supported via .NET, whether that’s using Visual Studio,
Xamarin Studio, MonoDevelop or
xbuild from the command line.
Project generation will have created a solution file in the same directory as Protobuild. You can open this with any of the IDEs to start working on your project.
When adding or removing files in your C# projects from Visual Studio, Xamarin
Studio or MonoDevelop, remember to save the projects in the IDE and then run
--resync to save your changes back to your definition