Warning These bindings are experimental, which means they can change at any time or be removed outright; nevertheless the plan is to provide a stable external C API to the Nix language and the Nix store.
The language library allows evaluating Nix expressions and interacting with Nix language values. The Nix store API is still rudimentary, and only allows initialising and connecting to a store for the Nix language evaluator to interact with.
Currently there are two ways to interface with the Nix language evaluator programmatically:
- Embedding the evaluator
- Writing language plug-ins
Embedding means you link the Nix C libraries in your program and use them from there. Adding a plug-in means you make a library that gets loaded by the Nix language evaluator, specified through a configuration option.
Many of the components and mechanisms involved are not yet documented, therefore please refer to the Nix source code for details. Additions to in-code documentation and the reference manual are highly appreciated.
The following examples, for simplicity, don't include error handling. See the Handling errors section for more information.
Embedding the Nix Evaluator
In this example we programmatically start the Nix language evaluator with a dummy store (that has no store paths and cannot be written to), and evaluate the Nix expression builtins.nixVersion
.
main.c:
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
void my_get_string_cb(const char * start, unsigned int n, void * user_data)
{
*((char **) user_data) = strdup(start);
}
int main()
{
char * version;
printf("Nix version: %s\n", version);
free(version);
return 0;
}
nix_err nix_gc_decref(nix_c_context *context, const void *object)
Decrement the garbage collector reference counter for the given object.
nix_err nix_value_force(nix_c_context *context, EvalState *state, nix_value *value)
Forces the evaluation of a Nix value.
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.
EvalState * nix_state_create(nix_c_context *context, const char **lookupPath, Store *store)
Create a new Nix language evaluator state.
nix_err nix_libexpr_init(nix_c_context *context)
Initialize the Nix language evaluator.
nix_value * nix_alloc_value(nix_c_context *context, EvalState *state)
Allocate a Nix value.
void nix_state_free(EvalState *state)
Frees a Nix state.
void nix_store_free(Store *store)
Deallocate a nix store and free any resources if not also held by other Store instances.
struct Store Store
Reference to a Nix store.
Definition nix_api_store.h:23
Store * nix_store_open(nix_c_context *context, const char *uri, const char ***params)
Open a nix store.
nix_err nix_get_string(nix_c_context *context, const nix_value *value, nix_get_string_callback callback, void *user_data)
Get the raw string.
Main entry for the libexpr C bindings.
Main entry for the libutil C bindings.
libexpr C bindings dealing with values
Represents a state of the Nix language evaluator.
Usage:
$ gcc main.c $(pkg-config nix-expr-c --libs --cflags) -o main
$ ./main
Nix version: 2.17
Writing a Nix language plug-in
In this example we add a custom primitive operation (primop) to builtins
. It will increment the argument if it is an integer and throw an error otherwise.
plugin.c:
} else {
}
}
void nix_plugin_entry() {
const char* args[] = {"n", NULL};
PrimOp *p =
nix_alloc_primop(NULL, increment, 1,
"increment", args,
"Example custom built-in function: increments an integer", NULL);
}
nix_err nix_set_err_msg(nix_c_context *context, nix_err err, const char *msg)
Set an error message on a nix context.
@ NIX_ERR_UNKNOWN
An unknown error occurred.
Definition nix_api_util.h:75
struct PrimOp PrimOp
PrimOp function.
Definition nix_api_value.h:68
nix_err nix_register_primop(nix_c_context *context, PrimOp *primOp)
add a primop to the builtins attribute set
PrimOp * nix_alloc_primop(nix_c_context *context, PrimOpFun fun, int arity, const char *name, const char **args, const char *doc, void *user_data)
Allocate a PrimOp.
ValueType nix_get_type(nix_c_context *context, const nix_value *value)
Get value type.
nix_err nix_init_int(nix_c_context *context, nix_value *value, int64_t i)
Set an int.
int64_t nix_get_int(nix_c_context *context, const nix_value *value)
Get int value.
This object stores error state.
Usage:
$ gcc plugin.c $(pkg-config nix-expr-c --libs --cflags) -shared -o plugin.so
$ nix --plugin-files ./plugin.so repl
nix-repl> builtins.increment 1
2