Nix 2.29.0
Nix, the purely functional package manager: C API (experimental)
|
Bindings to the Nix language evaluator. More...
Topics | |
Adding primops | |
GC | |
Reference counting and garbage collector operations. | |
Externals | |
Deal with external values. | |
Manipulating values | |
Functions to inspect and change Nix language values, represented by nix_value. |
Files | |
file | nix_api_expr.h |
Main entry for the libexpr C bindings. | |
file | nix_api_value.h |
libexpr C bindings dealing with values |
Data Structures | |
struct | EvalState |
Represents a state of the Nix language evaluator. More... |
Macros | |
#define | __has_c_attribute(x) |
#define | NIX_DEPRECATED(msg) |
#define | NIX_VALUE_CALL(context, state, value, fn, ...) |
Calls a Nix function with multiple arguments. |
Typedefs | |
typedef struct nix_eval_state_builder | nix_eval_state_builder |
Builder for EvalState. | |
typedef struct EvalState | EvalState |
typedef struct nix_value | nix_value |
A Nix language value, or thunk that may evaluate to a value. | |
typedef struct nix_value | nix_value |
typedef struct EvalState | EvalState |
typedef nix_value | Value |
typedef struct nix_realised_string | nix_realised_string |
String without placeholders, and realised store paths. |
Functions | |
NIX_DEPRECATED ("use nix_value instead") typedef nix_value Value | |
nix_err | nix_libexpr_init (nix_c_context *context) |
Initialize the Nix language evaluator. | |
nix_err | nix_expr_eval_from_string (nix_c_context *context, EvalState *state, const char *expr, const char *path, nix_value *value) |
Parses and evaluates a Nix expression from a string. | |
nix_err | nix_value_call (nix_c_context *context, EvalState *state, nix_value *fn, nix_value *arg, nix_value *value) |
Calls a Nix function with an argument. | |
nix_err | nix_value_call_multi (nix_c_context *context, EvalState *state, nix_value *fn, size_t nargs, nix_value **args, nix_value *value) |
Calls a Nix function with multiple arguments. | |
nix_err | nix_value_force (nix_c_context *context, EvalState *state, nix_value *value) |
Forces the evaluation of a Nix value. | |
nix_err | nix_value_force_deep (nix_c_context *context, EvalState *state, nix_value *value) |
Forces the deep evaluation of a Nix value. | |
nix_eval_state_builder * | nix_eval_state_builder_new (nix_c_context *context, Store *store) |
Create a new nix_eval_state_builder. | |
nix_err | nix_eval_state_builder_load (nix_c_context *context, nix_eval_state_builder *builder) |
Read settings from the ambient environment. | |
nix_err | nix_eval_state_builder_set_lookup_path (nix_c_context *context, nix_eval_state_builder *builder, const char **lookupPath) |
Set the lookup path for <...> expressions. | |
EvalState * | nix_eval_state_build (nix_c_context *context, nix_eval_state_builder *builder) |
Create a new Nix language evaluator state. | |
void | nix_eval_state_builder_free (nix_eval_state_builder *builder) |
Free a nix_eval_state_builder. | |
EvalState * | nix_state_create (nix_c_context *context, const char **lookupPath, Store *store) |
Create a new Nix language evaluator state. | |
void | nix_state_free (EvalState *state) |
Frees a Nix state. | |
nix_value * | nix_alloc_value (nix_c_context *context, EvalState *state) |
Allocate a Nix value. | |
nix_err | nix_value_incref (nix_c_context *context, nix_value *value) |
Increment the garbage collector reference counter for the given nix_value. | |
nix_err | nix_value_decref (nix_c_context *context, nix_value *value) |
Decrement the garbage collector reference counter for the given object. | |
nix_realised_string * | nix_string_realise (nix_c_context *context, EvalState *state, nix_value *value, bool isIFD) |
Realise a string context. | |
const char * | nix_realised_string_get_buffer_start (nix_realised_string *realised_string) |
Start of the string. | |
size_t | nix_realised_string_get_buffer_size (nix_realised_string *realised_string) |
Length of the string. | |
size_t | nix_realised_string_get_store_path_count (nix_realised_string *realised_string) |
Number of realised store paths. | |
const StorePath * | nix_realised_string_get_store_path (nix_realised_string *realised_string, size_t index) |
Get a store path. The store paths are stored in an arbitrary order. | |
void | nix_realised_string_free (nix_realised_string *realised_string) |
Free a realised string. |
Bindings to the Nix language evaluator.
See Embedding the Nix Evaluator for an example.
#define __has_c_attribute | ( | x | ) |
#define NIX_VALUE_CALL | ( | context, | |
state, | |||
value, | |||
fn, | |||
... ) |
Calls a Nix function with multiple arguments.
Technically these are functions that return functions. It is common for Nix functions to be curried, so this function is useful for calling them.
[out] | context | Optional, stores error information |
[in] | state | The state of the evaluation. |
[out] | value | The result of the function call. |
[in] | fn | The Nix function to call. |
[in] | ... | The arguments to pass to the function. |
A Nix language value, or thunk that may evaluate to a value.
Values are the primary objects manipulated in the Nix language. They are considered to be immutable from a user's perspective, but the process of evaluating a value changes its ValueType if it was a thunk. After a value has been evaluated, its ValueType does not change.
Evaluation in this context refers to the process of evaluating a single value object, also called "forcing" the value; see nix_value_force.
The evaluator manages its own memory, but your use of the C API must follow the reference counting rules.
nix_value * nix_alloc_value | ( | nix_c_context * | context, |
EvalState * | state ) |
Allocate a Nix value.
Owned by the GC. Use nix_gc_decref() when you're done with the pointer
[out] | context | Optional, stores error information |
[in] | state | nix evaluator state |
EvalState * nix_eval_state_build | ( | nix_c_context * | context, |
nix_eval_state_builder * | builder ) |
Create a new Nix language evaluator state.
Remember to nix_eval_state_builder_free after building the state.
[out] | context | Optional, stores error information |
[in] | builder | The builder to use and free |
void nix_eval_state_builder_free | ( | nix_eval_state_builder * | builder | ) |
nix_err nix_eval_state_builder_load | ( | nix_c_context * | context, |
nix_eval_state_builder * | builder ) |
Read settings from the ambient environment.
Settings are sourced from environment variables and configuration files, as documented in the Nix manual.
[out] | context | Optional, stores error information |
[out] | builder | The builder to modify. |
nix_eval_state_builder * nix_eval_state_builder_new | ( | nix_c_context * | context, |
Store * | store ) |
Create a new nix_eval_state_builder.
The settings are initialized to their default value. Values can be sourced elsewhere with nix_eval_state_builder_load.
[out] | context | Optional, stores error information |
[in] | store | The Nix store to use. |
nix_err nix_eval_state_builder_set_lookup_path | ( | nix_c_context * | context, |
nix_eval_state_builder * | builder, | ||
const char ** | lookupPath ) |
Set the lookup path for <...> expressions.
[in] | context | Optional, stores error information |
[in] | builder | The builder to modify. |
[in] | lookupPath | Null-terminated array of strings corresponding to entries in NIX_PATH. |
nix_err nix_expr_eval_from_string | ( | nix_c_context * | context, |
EvalState * | state, | ||
const char * | expr, | ||
const char * | path, | ||
nix_value * | value ) |
Parses and evaluates a Nix expression from a string.
[out] | context | Optional, stores error information |
[in] | state | The state of the evaluation. |
[in] | expr | The Nix expression to parse. |
[in] | path | The file path to associate with the expression. This is required for expressions that contain relative paths (such as ./.) that are resolved relative to the given directory. |
[out] | value | The result of the evaluation. You must allocate this yourself. |
nix_err nix_libexpr_init | ( | nix_c_context * | context | ) |
Initialize the Nix language evaluator.
This function must be called at least once, at some point before constructing a EvalState for the first time. This function can be called multiple times, and is idempotent.
[out] | context | Optional, stores error information |
void nix_realised_string_free | ( | nix_realised_string * | realised_string | ) |
Free a realised string.
[in] | realised_string |
size_t nix_realised_string_get_buffer_size | ( | nix_realised_string * | realised_string | ) |
Length of the string.
[in] | realised_string |
const char * nix_realised_string_get_buffer_start | ( | nix_realised_string * | realised_string | ) |
Start of the string.
[in] | realised_string |
const StorePath * nix_realised_string_get_store_path | ( | nix_realised_string * | realised_string, |
size_t | index ) |
Get a store path. The store paths are stored in an arbitrary order.
[in] | realised_string | |
[in] | index | index of the store path, must be less than the count |
size_t nix_realised_string_get_store_path_count | ( | nix_realised_string * | realised_string | ) |
Number of realised store paths.
[in] | realised_string |
EvalState * nix_state_create | ( | nix_c_context * | context, |
const char ** | lookupPath, | ||
Store * | store ) |
Create a new Nix language evaluator state.
For more control, use nix_eval_state_builder
[out] | context | Optional, stores error information |
[in] | lookupPath | Null-terminated array of strings corresponding to entries in NIX_PATH. |
[in] | store | The Nix store to use. |
void nix_state_free | ( | EvalState * | state | ) |
Frees a Nix state.
Does not fail.
[in] | state | The state to free. |
nix_realised_string * nix_string_realise | ( | nix_c_context * | context, |
EvalState * | state, | ||
nix_value * | value, | ||
bool | isIFD ) |
Realise a string context.
This will
[out] | context | Optional, stores error information |
[in] | value | Nix value, which must be a string |
[in] | state | Nix evaluator state |
[in] | isIFD | If true, disallow derivation outputs if setting allow-import-from-derivation is false. You should set this to true when this call is part of a primop. You should set this to false when building for your application's purpose. |
nix_err nix_value_call | ( | nix_c_context * | context, |
EvalState * | state, | ||
nix_value * | fn, | ||
nix_value * | arg, | ||
nix_value * | value ) |
Calls a Nix function with an argument.
[out] | context | Optional, stores error information |
[in] | state | The state of the evaluation. |
[in] | fn | The Nix function to call. |
[in] | arg | The argument to pass to the function. |
[out] | value | The result of the function call. |
nix_err nix_value_call_multi | ( | nix_c_context * | context, |
EvalState * | state, | ||
nix_value * | fn, | ||
size_t | nargs, | ||
nix_value ** | args, | ||
nix_value * | value ) |
Calls a Nix function with multiple arguments.
Technically these are functions that return functions. It is common for Nix functions to be curried, so this function is useful for calling them.
[out] | context | Optional, stores error information |
[in] | state | The state of the evaluation. |
[in] | fn | The Nix function to call. |
[in] | nargs | The number of arguments. |
[in] | args | The arguments to pass to the function. |
[out] | value | The result of the function call. |
nix_err nix_value_decref | ( | nix_c_context * | context, |
nix_value * | value ) |
Decrement the garbage collector reference counter for the given object.
[out] | context | Optional, stores error information |
[in] | value | The object to stop referencing |
nix_err nix_value_force | ( | nix_c_context * | context, |
EvalState * | state, | ||
nix_value * | value ) |
Forces the evaluation of a Nix value.
The Nix interpreter is lazy, and not-yet-evaluated values can be of type NIX_TYPE_THUNK instead of their actual value.
This function mutates such a nix_value, so that, if successful, it has its final type.
[out] | context | Optional, stores error information |
[in] | state | The state of the evaluation. |
[in,out] | value | The Nix value to force. |
nix_err nix_value_force_deep | ( | nix_c_context * | context, |
EvalState * | state, | ||
nix_value * | value ) |
Forces the deep evaluation of a Nix value.
Recursively calls nix_value_force
[out] | context | Optional, stores error information |
[in] | state | The state of the evaluation. |
[in,out] | value | The Nix value to force. |
nix_err nix_value_incref | ( | nix_c_context * | context, |
nix_value * | value ) |
Increment the garbage collector reference counter for the given nix_value.
The Nix language evaluator C API keeps track of alive objects by reference counting. When you're done with a refcounted pointer, call nix_value_decref().
[out] | context | Optional, stores error information |
[in] | value | The object to keep alive |