Class Recipe

pkgxx/recipe.moon

Operations and data on single recipes.

It is useful to know that a Recipe can generate multiple packages.

Recipes are created with one default package, that will inherit most of its properties, including its name, version, and so on.

See also
Package
Context
Atom

Constructors

Recipe (context) object

Recipe constructor, that’s meant to be used privately only.

To create new Recipe objects, use Context\newRecipe.

Arguments
ArgumentTypeDescription
contextContextpkgxx Context in which to import the recipe.
See also
Context.newRecipe

Instance

name: string | nil

Name of the recipe.


version: string | nil

Version of the software or content to be packaged.


release: number

Version of the recipe itself.

The release attribute should always be incremented when the recipe is updated.

This attribute must have a minimum value of 1 and must be an integer.


packager: string | nil

The person who wrote the recipe.

Should have the following format: packager name <mail@example>.


maintainer: string | nil

The person who updates and maintains the recipe.

Recipes imported from package.toml files have their maintainer default to @packager.

The format of this field is the same as that of @packager.

See also
packager

url: string | nil

Homepage of the packaged project.


sources: table

List of sources needed to build the recipe and its packages.

Each member of this field must be an instance of Source.

See also
Source
addSource

buildInstructions: {configure: Builder, build: Builder, install: Builder}

Instructions to build the software.

Contains three fields: configure, build and install, which must all be instances of Builder.

See also
Builder
Issue
Not enough documentation over here~

buildDependencies: table

A list of Atoms describing the recipe’s build-time dependencies.

Build-dependencies are shared between all packages described by a recipe.

See also
Atom

watch: table | nil

Metadata to check automagically if the recipe is out of date.

Issue
There should be a Watch class instead of arbitrary, unchecked tables.
Issue
@watch is relatively easy to test… and yet has no test.
Issue
A part of it also depends on html-xml-utils or something like that…

dirname: string | nil

Describes the name of the directory in which the main sources are stored.

This value might be used by modules to configure their build process.

Several default values can be applied during Recipe\finalize:

  • set to "#{@name}-#{@version}" if @version exists,
  • set to @name otherwise.

options: table

Options with which to build the package.

.options is a field of arbitrary strings from which modules can take instructions.

See the various postBuild modules for specific entries to add to the .options field.


importTOML (filename) object

Imports a recipe’s data from a package.toml file.

Arguments
ArgumentTypeDescription
filenamestringFilename of the recipe to parse.

addSource (source) true | nil, string

Adds sources to the Recipe.

If the sources are provided as a URL, they will automatically be converted to a Source. The arrow notation (url -> filename) is supported if you want or need to name the downloaded file.

Arguments
ArgumentTypeDescription
sourcestring | SourceURL or Source that describes the sources to add.
Return values
TypeDescription
trueAll clear.
nil, stringSource parsing error or filename collision.

addPackage (name) Package

Defines a new Package in the recipe.

Arguments
ArgumentTypeDescription
namestringThe `name` attribute of the Package to create.
Return values
TypeDescription
PackageThe newly created Package.

finalize ! nil

Finalizes a recipe and makes it ready for use.

All missing or uninitialized attributes will be set to safe values for further operations.

Recipes must be finalized before calling @{Recipe\build} or @{Recipe\package}.

Return values
TypeDescription
nil

getTargets ! function

Lists the filenames and packages this recipe defines.

Return values
TypeDescription
functionIterator over the pairs of filename and Package defined by the Recipe.
See also
Package

getLogFile ! string

Return values
TypeDescription
stringLocation of the recipe’s log file.

checkRecipe ! object


hasPackage (name) boolean

Checks that a Recipe defines a Package.

Arguments
ArgumentTypeDescription
namestringName of the package.
Return values
TypeDescription
booleanWhether the Recipe contains a Package with the given name or not.
Info
Will probably get patched to identify Packages based on an Atom and not just a name string.

buildingDirectory ! string

Return values
TypeDescription
stringThe directory in which the software will be built.

packagingDirectory (name) string

Arguments
ArgumentTypeDescription
name
Return values
TypeDescription
stringThe “fake installation root” of the package, as used during build.

buildNeeded ! true | false

Checks whether the recipe’s packages need updating or rebuilding.

Return values
TypeDescription
trueRecipe needs rebuild.
falseEverything is up to date.

checkDependencies ! nil

Checks whether the recipe’s dependencies and build-dependencies are installed, and tries to install them if they are not.

Return values
TypeDescription
nil

installDependency (name) object

Installs a package by name.

Arguments
ArgumentTypeDescription
namestringName of the package to install.
Issue
Will be moved to Context at some point.

download ! boolean

Downloads the recipe’s sources.

Return values
TypeDescription
booleanBoolean indicating whether or not the downloads succeeded.

updateVersion ! object

Generates the recipe’s version from its sources.

Is useless for recipes with static versions, but is useful if a recipe is of a development version from a git repository or any similar situation.


build ! object

Builds the recipe.

This method does not build the packages themselves. The package method does that.

See also
Package
Recipe\package
Recipe\finalize

package ! object

Creates packages from the built software.

See also
Recipe\build
Recipe\finalize

clean ! boolean

Removes the recipe’s temporary building directories.

Return values
TypeDescription
booleanWhether removing the files succeeded or not.

lint ! number

Prints potential defects or missing data in the recipe.

It prints the defects themselves on stderr, and returns the number of defects found.

Return values
TypeDescription
numberNumber of defects found in the recipe’s current configuration.

isUpToDate ! true, string | false, string

Checks whether or not the recipe is up to date.

It may need access to recent sources to do so.

Return values
TypeDescription
true, stringVersion is up to date. Also returns the version.
false, stringRecipe is outdated. Returns the latest version available.
See also
Recipe\download

depTree ! object

Generates a dependency tree for the recipe.

May need access to other recipes.


__tostring ! object

Recipe can be safely converted to a debug string.