mirror of
https://github.com/privatevoid-net/nix-super.git
synced 2024-11-10 00:08:07 +02:00
C API: clarify some documentation
This commit is contained in:
parent
5d82d6e733
commit
9d380c0f76
5 changed files with 22 additions and 19 deletions
|
@ -59,8 +59,9 @@ typedef void Value; // nix::Value
|
|||
/**
|
||||
* @brief Initialize the Nix language evaluator.
|
||||
*
|
||||
* This function should be called before creating a State.
|
||||
* This function can be called multiple times.
|
||||
* This function must be called at least once,
|
||||
* at some point before constructing a State for the first time.
|
||||
* This function can be called multiple times, and is idempotent.
|
||||
*
|
||||
* @param[out] context Optional, stores error information
|
||||
* @return NIX_OK if the initialization was successful, an error code otherwise.
|
||||
|
@ -106,7 +107,8 @@ nix_err nix_value_call(nix_c_context *context, State *state, Value *fn,
|
|||
*
|
||||
* @note You don't need this function for basic API usage, since all functions
|
||||
* that return a value call it for you. The only place you will see a
|
||||
* NIX_TYPE_THUNK is in the primop callback.
|
||||
* NIX_TYPE_THUNK is in the arguments that are passed to a PrimOp function
|
||||
* you supplied to nix_alloc_primop.
|
||||
*
|
||||
* @param[out] context Optional, stores error information
|
||||
* @param[in] state The state of the evaluation.
|
||||
|
|
|
@ -66,12 +66,12 @@ typedef struct ExternalValue ExternalValue;
|
|||
*/
|
||||
/** @brief Function pointer for primops
|
||||
* @param[in] state Evaluator state
|
||||
* @param[in] pos position of function call
|
||||
* @param[in] args list of arguments
|
||||
* @param[out] v return value
|
||||
* @param[in] pos Call position, opaque index into the state's position table.
|
||||
* @param[in] args list of arguments. Note that these can be thunks and should be forced using nix_value_force before use.
|
||||
* @param[out] ret return value
|
||||
* @see nix_alloc_primop, nix_set_primop
|
||||
*/
|
||||
typedef void (*PrimOpFun)(State *state, int pos, Value **args, Value *v);
|
||||
typedef void (*PrimOpFun)(State *state, int pos, Value **args, Value *ret);
|
||||
|
||||
/** @brief Allocate a PrimOp
|
||||
*
|
||||
|
@ -80,9 +80,9 @@ typedef void (*PrimOpFun)(State *state, int pos, Value **args, Value *v);
|
|||
*
|
||||
* @param[out] context Optional, stores error information
|
||||
* @param[in] fun callback
|
||||
* @param[in] arity expected amount of function arguments
|
||||
* @param[in] arity expected number of function arguments
|
||||
* @param[in] name function name
|
||||
* @param[in] args array of argument names
|
||||
* @param[in] args array of argument names, NULL-terminated
|
||||
* @param[in] doc optional, documentation for this primop
|
||||
* @return primop, or null in case of errors
|
||||
* @see nix_set_primop
|
||||
|
|
|
@ -103,7 +103,7 @@ StorePath *nix_store_parse_path(nix_c_context *context, Store *store,
|
|||
|
||||
nix_err nix_store_build(nix_c_context *context, Store *store, StorePath *path,
|
||||
void *userdata,
|
||||
void (*iter)(void *userdata, const char *,
|
||||
void (*callback)(void *userdata, const char *,
|
||||
const char *)) {
|
||||
if (context)
|
||||
context->last_err_code = NIX_OK;
|
||||
|
@ -114,11 +114,11 @@ nix_err nix_store_build(nix_c_context *context, Store *store, StorePath *path,
|
|||
.outputs = nix::OutputsSpec::All{},
|
||||
},
|
||||
});
|
||||
if (iter) {
|
||||
if (callback) {
|
||||
for (auto &[outputName, outputPath] :
|
||||
store->ptr->queryDerivationOutputMap(path->path)) {
|
||||
auto op = store->ptr->printStorePath(outputPath);
|
||||
iter(userdata, outputName.c_str(), op.c_str());
|
||||
callback(userdata, outputName.c_str(), op.c_str());
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
@ -36,7 +36,7 @@ typedef struct StorePath StorePath;
|
|||
nix_err nix_libstore_init(nix_c_context *context);
|
||||
|
||||
/**
|
||||
* @brief Loads plugins specified in the settings
|
||||
* @brief Loads the plugins specified in Nix's plugin-files setting.
|
||||
*
|
||||
* Call this once, after calling your desired init functions and setting
|
||||
* relevant settings.
|
||||
|
@ -111,17 +111,17 @@ bool nix_store_is_valid_path(nix_c_context *context, Store *store,
|
|||
/**
|
||||
* @brief Realise a Nix store path
|
||||
*
|
||||
* Blocking, calls cb once for each built output
|
||||
* Blocking, calls callback once for each realisedoutput
|
||||
*
|
||||
* @param[out] context Optional, stores error information
|
||||
* @param[in] store Nix Store reference
|
||||
* @param[in] path Path to build
|
||||
* @param[in] userdata data to pass to every callback invocation
|
||||
* @param[in] cb called for every built output
|
||||
* @param[in] callback called for every realised output
|
||||
*/
|
||||
nix_err nix_store_build(nix_c_context *context, Store *store, StorePath *path,
|
||||
void *userdata,
|
||||
void (*cb)(void *userdata, const char *outname,
|
||||
void (*callback)(void *userdata, const char *outname,
|
||||
const char *out));
|
||||
|
||||
/**
|
||||
|
|
|
@ -1156,9 +1156,10 @@ public:
|
|||
this, {}, "plugin-files",
|
||||
R"(
|
||||
A list of plugin files to be loaded by Nix. Each of these files will
|
||||
be dlopened by Nix, allowing them to affect execution through static
|
||||
initialization. In particular, these plugins may construct static
|
||||
instances of RegisterPrimOp to add new primops or constants to the
|
||||
be dlopened by Nix. If they contain the symbol `nix_plugin_entry()`,
|
||||
this symbol will be called. Alternatively, they can affect execution
|
||||
through static initialization. In particular, these plugins may construct
|
||||
static instances of RegisterPrimOp to add new primops or constants to the
|
||||
expression language, RegisterStoreImplementation to add new store
|
||||
implementations, RegisterCommand to add new subcommands to the `nix`
|
||||
command, and RegisterSetting to add new nix config settings. See the
|
||||
|
|
Loading…
Reference in a new issue