diff --git a/src/libexpr/c/nix_api_expr.h b/src/libexpr/c/nix_api_expr.h index 926d0f7a0..a6b902f96 100644 --- a/src/libexpr/c/nix_api_expr.h +++ b/src/libexpr/c/nix_api_expr.h @@ -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. diff --git a/src/libexpr/c/nix_api_value.h b/src/libexpr/c/nix_api_value.h index a4e643317..f4d9c9584 100644 --- a/src/libexpr/c/nix_api_value.h +++ b/src/libexpr/c/nix_api_value.h @@ -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 diff --git a/src/libstore/c/nix_api_store.cc b/src/libstore/c/nix_api_store.cc index 0cc1d1983..7b5391034 100644 --- a/src/libstore/c/nix_api_store.cc +++ b/src/libstore/c/nix_api_store.cc @@ -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()); } } } diff --git a/src/libstore/c/nix_api_store.h b/src/libstore/c/nix_api_store.h index 36d712f01..43ded1860 100644 --- a/src/libstore/c/nix_api_store.h +++ b/src/libstore/c/nix_api_store.h @@ -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)); /** diff --git a/src/libstore/globals.hh b/src/libstore/globals.hh index e6acf0a4f..1d54cfe56 100644 --- a/src/libstore/globals.hh +++ b/src/libstore/globals.hh @@ -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