Getting Started

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.

Download Protobuild

First you’ll need to download Protobuild itself:

Download Protobuild

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.

Note

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>

Replace <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 with mono (as with all commands in this documentation that execute Protobuild).

This will create a Protobuild module using the template at the specified URL. You can find more templates by searching the Protobuild package index.

Tip

Common starting templates (including templates for libraries) can be found under the commons organisation on the Protobuild index.

Note

The term 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 the term 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:

• Defining Application Projects
• Defining Console Projects
• Defining Library Projects
• Defining Content Projects
• Defining External Projects

Generating projects

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

Tip

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 Windows, use:

$ 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

Tip

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

Note

All of the above commands accept a platform as an argument. For more detail on what commands are available, try --help.

Building code

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 msbuild / 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 either --sync or --resync to save your changes back to your definition files.

Further reading

We recommend reading up on the different available project types (linked above in Start from scratch). You can also refer to the Frequently Asked Questions.