Creating a Package

This is a guide for creating a Buckaroo recipe from a GitHub, BitBucket or GitLab project. This is the quickest way to create and manage a package that already lives in source-control. It is also recommended, since it allows you to control updates to your recipe.

For this guide, we will be adding Buckaroo support for an example project. However, the steps are generic, so you should be able to follow them using your own project.

If you would like to jump straight to a working GitHub recipe, take a look at LoopPerfect/neither. The important files are BUCK and buckaroo.json.

Requirements

To follow this guide, you will need the following:

The steps are nearly identical for BitBucket and GitLab.

1. Fork the example project

Fork the example project on GitHub.

2. Fetch the Project

Next, fetch your fork from GitHub using Git:

git clone https://github.com/<YOUR_GITHUB_USERNAME>/buckaroo-github-example.git
cd buckaroo-github-example

3. Ensure that the project builds with Buck

All Buckaroo packages build with Buck, so we need to make sure that the BUCK files are correct.

In our example, we have a single library called example. Try building it using Buck:

buck build :example

If you are using your own project that does not yet build with Buck, then you will need to write the appropriate Buck files. Head over to the Buck website for more guidance, or you can follow this article on Hackernoon.

Note

To work with Buckaroo, your Buck target must be marked PUBLIC. To do this, simply add the following to your target definition:

visibility = [
  'PUBLIC',
]

4. Create the Project File

Now that we are sure the project can build with Buck, we need to create a project file. The project file gives Buckaroo various bits of meta-data about your recipe.

buckaroo init

This will create a buckaroo.json file. Open it, and ensure that the target field points to your Buck target.

For our example, the target is "example". The final buckaroo.json file might look like this:

{
  "name": "buckaroo-github-example",
  "target": "example"
}

Commit the project file to GitHub:

git add buckaroo.json
git commit -m "Adds Buckaroo project file"
git push

5. Create a release

Head over to the GitHub web-page for your project and create a release. It is important that you name the release in a format that Buckaroo understands. Buckaroo expects a version number prefixed with a "v". Some valid names are:

  • "v1.0.0"
  • "v0.2"
  • "v3"

For this guide, we will name the release "v0.1.0".

6. Test your package

Create a new folder alongside your project directory:

cd ../
mkdir test
cd test

Create a Buckaroo project in this directory:

buckaroo quickstart

Now we can install the GitHub recipe:

buckaroo install github+<YOUR_GITHUB_USERNAME>/buckaroo-github-example

You should see a few changes to your working directory:

  • buckaroo.lock.json will contain an exact version of your GitHub recipe
  • buckaroo/ will contain a copy of your recipe
  • BUCKAROO_DEPS will have been generated, ready to include in your BUCK file.

Open test/src/main.cpp and update it to use your recipe:

#include <iostream>
#include <sum.hpp>

int main() {
  std::cout << "sum(1, 2) = " << sum(1, 2) << std::endl;
  return 0;
}

Now run your program using Buck:

buck run :test

If everything has worked correctly, you will see the following output:

sum(1, 2) = 3