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",
  "github+loopperfect/neither": "*"
}

The dependencies element defines the modules that the recipe requires to build. These are of the following format:

(<source>+)?<owner>/<project>: <version>

The source section is optional and is used to refer to recipes outside of the official cookbook. The most common source is GitHub (see github), and more will be added over time.

A small DSL is provided for versioning:

*                    // Any version
v1                   // Exactly version 1.0.0
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.