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:
- Git
- A GitHub account
- Buckaroo (see Installation)
- Buck
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 recipebuckaroo/
will contain a copy of your recipeBUCKAROO_DEPS
will have been generated, ready to include in yourBUCK
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