Definition for a class of external values
Create and implement one of these, then pass it to nix_create_external_value
Make sure to keep it alive while the external value lives.
Optional functions can be set to NULL
Clear the error message from a nix context.
This is performed implicitly by all functions that accept a context, so
this won’t be necessary in most cases.
However, if you want to clear the error message without calling another
function, you can use this.
Example use case: a higher order function that helps with error handling,
to make it more robust in the following scenario:
Retrieves the error message from errorInfo in a context.
Used to inspect nix Error messages.
@pre This function should only be called after a previous nix function has
returned a NIX_ERR_NIX_ERROR
@addtogroup errors
Retrieves the most recent error message from a context.
@pre This function should only be called after a previous nix function has
returned an error.
Retrieves the error name from a context.
Used to inspect nix Error messages.
@pre This function should only be called after a previous nix function has
returned a NIX_ERR_NIX_ERROR
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.
Increment the garbage collector reference counter for the given object.
The Nix language evaluator C API keeps track of alive objects by reference
counting. When you’re done with a refcounted pointer, call
nix_gc_decref().
Set the value to a thunk that will perform a function application when
needed. Thunks may be put into attribute sets and lists to perform some
computation lazily; on demand. However, note that in some places, a
thunk must not be returned, such as in the return value of a PrimOp.
In such cases, you may use nix_value_call() instead (but note the
different argument order).
@}*/ /** @name Initializers
Values are typically “returned” by initializing already allocated memory
that serves as the return value. For this reason, the construction of
values is not tied their allocation. Nix is a language with immutable
values. Respect this property by only initializing Values once; and only
initialize Values that are meant to be initialized by you. Failing to
adhere to these rules may lead to undefined behavior.
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.
Like nix_libstore_init, but does not load the Nix configuration.
This is useful when external configuration is not desired, such as when
running unit tests.
Initializes nix_libutil and its dependencies.
This function can be called multiple times, but should be called at least
once prior to any other nix function.
add a primop to the builtins attribute set
Only applies to States created after this call.
Moves your PrimOp content into the global evaluator
registry, meaning your input PrimOp pointer is no longer usable.
You are free to remove your references to it,
after which it will be garbage collected.
Set an error message on a nix context.
This should be used when you want to throw an error from a PrimOp
callback. All other use is internal to the API.
@defgroup settings Nix configuration settings
Retrieves a setting from the nix global configuration.
This function requires nix_libutil_init() to be called at least once prior
to its use.
Sets a setting in the nix global configuration.
Use “extra-” to append to the setting’s value.
Settings only apply for new State%s. Call nix_plugins_init() when you are
done with the settings to load any plugins.
Get the physical location of a store path
A store may reside at a different location than its storeDir suggests.
This situation is called a relocated store.
Relocated stores are used during NixOS installation, as well as in
restricted computing environments that don’t offer a writable
/nix/store. Not all types of stores support this operation.
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.
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.
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().