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.