mirror of
https://github.com/privatevoid-net/nix-super.git
synced 2024-11-10 08:16:15 +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.
|
* @brief Initialize the Nix language evaluator.
|
||||||
*
|
*
|
||||||
* This function should be called before creating a State.
|
* This function must be called at least once,
|
||||||
* This function can be called multiple times.
|
* 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
|
* @param[out] context Optional, stores error information
|
||||||
* @return NIX_OK if the initialization was successful, an error code otherwise.
|
* @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
|
* @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
|
* 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[out] context Optional, stores error information
|
||||||
* @param[in] state The state of the evaluation.
|
* @param[in] state The state of the evaluation.
|
||||||
|
|
|
@ -66,12 +66,12 @@ typedef struct ExternalValue ExternalValue;
|
||||||
*/
|
*/
|
||||||
/** @brief Function pointer for primops
|
/** @brief Function pointer for primops
|
||||||
* @param[in] state Evaluator state
|
* @param[in] state Evaluator state
|
||||||
* @param[in] pos position of function call
|
* @param[in] pos Call position, opaque index into the state's position table.
|
||||||
* @param[in] args list of arguments
|
* @param[in] args list of arguments. Note that these can be thunks and should be forced using nix_value_force before use.
|
||||||
* @param[out] v return value
|
* @param[out] ret return value
|
||||||
* @see nix_alloc_primop, nix_set_primop
|
* @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
|
/** @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[out] context Optional, stores error information
|
||||||
* @param[in] fun callback
|
* @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] 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
|
* @param[in] doc optional, documentation for this primop
|
||||||
* @return primop, or null in case of errors
|
* @return primop, or null in case of errors
|
||||||
* @see nix_set_primop
|
* @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,
|
nix_err nix_store_build(nix_c_context *context, Store *store, StorePath *path,
|
||||||
void *userdata,
|
void *userdata,
|
||||||
void (*iter)(void *userdata, const char *,
|
void (*callback)(void *userdata, const char *,
|
||||||
const char *)) {
|
const char *)) {
|
||||||
if (context)
|
if (context)
|
||||||
context->last_err_code = NIX_OK;
|
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{},
|
.outputs = nix::OutputsSpec::All{},
|
||||||
},
|
},
|
||||||
});
|
});
|
||||||
if (iter) {
|
if (callback) {
|
||||||
for (auto &[outputName, outputPath] :
|
for (auto &[outputName, outputPath] :
|
||||||
store->ptr->queryDerivationOutputMap(path->path)) {
|
store->ptr->queryDerivationOutputMap(path->path)) {
|
||||||
auto op = store->ptr->printStorePath(outputPath);
|
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);
|
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
|
* Call this once, after calling your desired init functions and setting
|
||||||
* relevant settings.
|
* relevant settings.
|
||||||
|
@ -111,17 +111,17 @@ bool nix_store_is_valid_path(nix_c_context *context, Store *store,
|
||||||
/**
|
/**
|
||||||
* @brief Realise a Nix store path
|
* @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[out] context Optional, stores error information
|
||||||
* @param[in] store Nix Store reference
|
* @param[in] store Nix Store reference
|
||||||
* @param[in] path Path to build
|
* @param[in] path Path to build
|
||||||
* @param[in] userdata data to pass to every callback invocation
|
* @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,
|
nix_err nix_store_build(nix_c_context *context, Store *store, StorePath *path,
|
||||||
void *userdata,
|
void *userdata,
|
||||||
void (*cb)(void *userdata, const char *outname,
|
void (*callback)(void *userdata, const char *outname,
|
||||||
const char *out));
|
const char *out));
|
||||||
|
|
||||||
/**
|
/**
|
||||||
|
|
|
@ -1156,9 +1156,10 @@ public:
|
||||||
this, {}, "plugin-files",
|
this, {}, "plugin-files",
|
||||||
R"(
|
R"(
|
||||||
A list of plugin files to be loaded by Nix. Each of these files will
|
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
|
be dlopened by Nix. If they contain the symbol `nix_plugin_entry()`,
|
||||||
initialization. In particular, these plugins may construct static
|
this symbol will be called. Alternatively, they can affect execution
|
||||||
instances of RegisterPrimOp to add new primops or constants to the
|
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
|
expression language, RegisterStoreImplementation to add new store
|
||||||
implementations, RegisterCommand to add new subcommands to the `nix`
|
implementations, RegisterCommand to add new subcommands to the `nix`
|
||||||
command, and RegisterSetting to add new nix config settings. See the
|
command, and RegisterSetting to add new nix config settings. See the
|
||||||
|
|
Loading…
Reference in a new issue