wroclaw-git-backups/nix
1
0
Fork 0
mirror of https://github.com/NixOS/nix synced 2025-07-06 21:41:48 +02:00
Code Activity

C API: rename State to EvalState

Browse source
This commit is contained in:
José Luis Lafuente 2024-01-10 11:58:35 +01:00 • committed by José Luis Lafuente
parent 24604d024a
commit 535694122e
No known key found for this signature in database
GPG key ID: 8A3455EBE455489A
9 changed files with 85 additions and 64 deletions
Download patch file Download diff file Expand all files Collapse all files

49
doc/external-api/README.md
View file

@ -1,30 +1,40 @@
# Getting started
> **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.
> **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.
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:
Currently there are two ways to interface with the Nix language evaluator programmatically:
1. Embedding the evaluator
2. 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.
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](https://github.com/NixOS/nix/) for details.
Additions to in-code documentation and the reference manual are highly appreciated.
Many of the components and mechanisms involved are not yet documented, therefore
please refer to the [Nix source code](https://github.com/NixOS/nix/) 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](@ref errors) section for more information.
The following examples, for simplicity, don't include error handling. See the
[Handling errors](@ref 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`.
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:**
```C
#include <nix_api_util.h>
#include <nix_api_expr.h>
@ -35,7 +45,7 @@ int main() {
nix_libexpr_init(NULL);
Store* store = nix_store_open(NULL, "dummy://", NULL);
State* state = nix_state_create(NULL, NULL, store); // empty search path (NIX_PATH)
EvalState* state = nix_state_create(NULL, NULL, store); // empty search path (NIX_PATH)
Value *value = nix_alloc_value(NULL, state);
nix_expr_eval_from_string(NULL, state, "builtins.nixVersion", ".", value);
@ -50,24 +60,26 @@ int main() {
```
**Usage:**
```ShellSession
$ 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.
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:**
```C
#include <nix_api_util.h>
#include <nix_api_expr.h>
#include <nix_api_value.h>
void increment(void* user_data, nix_c_context* ctx, State* state, Value** args, Value* v) {
void increment(void* user_data, nix_c_context* ctx, EvalState* state, Value** args, Value* v) {
nix_value_force(NULL, state, args[0]);
if (nix_get_type(NULL, args[0]) == NIX_TYPE_INT) {
nix_set_int(NULL, v, nix_get_int(NULL, args[0]) + 1);
@ -85,6 +97,7 @@ void nix_plugin_entry() {
```
**Usage:**
```ShellSession
$ gcc plugin.c $(pkg-config nix-expr-c --libs --cflags) -shared -o plugin.so
$ nix --plugin-files ./plugin.so repl