Anatomy of a Recipe¶
A Buckaroo recipe is a file that describes a module that can be imported into your projects. Recipes are encoded as JSON.
Example¶
For example, here’s a recipe for the Beast HTTP library:
{
"name": "Beast",
"license": "BSL-1.0",
"url": "https://github.com/vinniefalco/beast",
"github": {
"owner": "vinniefalco",
"project": "beast"
},
"versions": {
"0.0.1": {
"source": {
"url": "https://github.com/vinniefalco/Beast/archive/6d5547a32c50ec95832c4779311502555ab0ee1f.zip",
"sha256": "8a600dfa3394164f79ad7dfa6942d8d4b6c6c7e5b8cc9b5f82519b682db25aae",
"subPath": "Beast-6d5547a32c50ec95832c4779311502555ab0ee1f"
},
"buck": {
"url": "https://raw.githubusercontent.com/njlr/Beast/71d1bde64bf5ee52579441b00ad446959231d8d2/BUCK",
"sha256": "1dce5d9f5c883e193e54c2dfc033a5485b9e8e87bb34d8c38ab03ed148ccd968"
},
"dependencies": {
"boost/range": "1.63.0",
"boost/intrusive": "1.63.0",
"boost/lexical-cast": "1.63.0",
"boost/math": "1.63.0",
"boost/system": "1.63.0",
"boost/asio": "1.63.0"
}
}
}
}
Name¶
"name": "Beast",
This is the friendly name of the package.
Note that the file-name of the recipe is the identifier used by the install
command, so the name
field may contain spaces, etc.
Meta-data¶
"license": "BSL-1.0",
"url": "https://github.com/vinniefalco/beast",
"github": {
"owner": "vinniefalco",
"project": "beast"
},
This optional meta-data is used to generate the pages on buckaroo.pm. Note that the license should be a comma-separated list of SPDX codes.
Versions¶
"versions": {
The versions
element is a dictionary of semantic versions to source locations.
"0.0.1": {
"source": {
"url": "https://github.com/vinniefalco/Beast/archive/6d5547a32c50ec95832c4779311502555ab0ee1f.zip",
"sha256": "8a600dfa3394164f79ad7dfa6942d8d4b6c6c7e5b8cc9b5f82519b682db25aae",
"subPath": "Beast-6d5547a32c50ec95832c4779311502555ab0ee1f"
},
"buck": {
"url": "https://raw.githubusercontent.com/njlr/Beast/71d1bde64bf5ee52579441b00ad446959231d8d2/BUCK",
"sha256": "1dce5d9f5c883e193e54c2dfc033a5485b9e8e87bb34d8c38ab03ed148ccd968"
},
"dependencies": {
"boost/range": "1.63.0",
"boost/intrusive": "1.63.0",
"boost/lexical-cast": "1.63.0",
"boost/math": "1.63.0",
"boost/system": "1.63.0",
"boost/asio": "1.63.0"
}
}
Each version object contains information on how to fetch the source-code. In case the source-code does not contain a BUCK
file, one may be injected using the information in the buck
element.
Source¶
"source": {
"url": "https://github.com/vinniefalco/Beast/archive/6d5547a32c50ec95832c4779311502555ab0ee1f.zip",
"sha256": "8a600dfa3394164f79ad7dfa6942d8d4b6c6c7e5b8cc9b5f82519b682db25aae",
"subPath": "Beast-6d5547a32c50ec95832c4779311502555ab0ee1f"
},
Every source
should point to a zip-file containing the source-code of the module. It is hashed to ensure integrity, so always choose a URL that is stable.
The subPath
element can be used to change the root of the source-code.
For example, suppose the zip-file has this structure:
.
+-- module.zip
+-- sources
+-- include
+-- math.hpp
+-- utils.hpp
If the subPath
is "sources/include"
, then the extracted code would be:
.
+-- math.hpp
+-- utils.hpp
This feature is particularly useful for GitHub, which puts source-code into a sub-folder called <project>-<commit>
.
Buck¶
"buck": {
"url": "https://raw.githubusercontent.com/njlr/Beast/71d1bde64bf5ee52579441b00ad446959231d8d2/BUCK",
"sha256": "1dce5d9f5c883e193e54c2dfc033a5485b9e8e87bb34d8c38ab03ed148ccd968"
},
The buck
element points to a remote Buck definition. If present, the remote BUCK
file gets saved into the root folder of the source-code. This allows us to support packages that do not currently support Buck.
The buck
element is only required when the source-code does not already contain a BUCK
file.
Dependencies¶
"dependencies": {
"boost/range": "1.63.0",
"boost/intrusive": "1.63.0",
"boost/lexical-cast": "1.63.0",
"boost/math": "1.63.0",
"boost/system": "1.63.0",
"boost/asio": "1.63.0"
}
The dependencies
element defines the modules that the recipe requires to build. These are of the following format:
<owner>/<project>: <version>
A small DSL is provided for versioning:
* // Any version
2 // Exactly version 2.0.0
1.2 // Exactly version 1.2.0
1.2.3 // Exactly version 1.2.3
1.0.1 - 4.3 // Between 1.0.1 and 4.3 inclusive
[ 7.2, 7.3, 8 ] // Either 7.2.0, 7.3.0 or 8.0.0
>= 4.7 // Version 4.7 or greater
<= 6.5.1 // Version 6.5.1 or greater
When multiple versions of a dependency can be resolved, the higher version is always chosen.