Docs for erlfdb module

README.md

@@ -2,53 +2,70 @@
 
 [![CI](https://github.com/foundationdb-beam/erlfdb/actions/workflows/ci.yml/badge.svg)](https://github.com/foundationdb-beam/erlfdb/actions/workflows/ci.yml)
 
-This project is a NIF wrapper for the FoundationDB C API. Documentation on
-the main API can be found [here][fdb_docs].
+An Erlang library that wraps the [FoundationDB C API](https://apple.github.io/foundationdb/api-c.html) with a NIF.
 
-This project also provides a conforming implementation of the [Tuple] and
-[Directory] layers.
+We also provide a conforming implementation of the [Tuple] and [Directory] layers.
 
-[fdb_docs]: https://apple.github.io/foundationdb/api-c.html
 [Tuple]: https://github.com/apple/foundationdb/blob/master/design/tuple.md
 [Directory]: https://apple.github.io/foundationdb/developer-guide.html#directories
 
 This project originated as [apache/couchdb-erlfdb](https://github.com/apache/couchdb-erlfdb). This fork
-was created in early 2024 to continue development of the project.
+was created in early 2024 to continue development.
 
-## Building
+## Dependencies
 
-Assuming you have installed the FoundationDB C API library, building erlfdb
-is as simple as:
+Refer to FoundationDB's [Getting Started on Linux] or [Getting Started on macOS].
 
-    $ rebar3 compile
+[Getting Started on Linux]: https://apple.github.io/foundationdb/getting-started-linux.html
+[Getting Started on macOS]: https://apple.github.io/foundationdb/getting-started-mac.html
 
-Alternatively, adding erlfdb as a rebar dependency should Just Work ®.
+Install the foundationdb-clients package to run erlfdb as a client to an existing
+FoundationDB database.
 
-Documentation for installing FoundationDB can be found [here for macOS]
-or [here for Linux].
+Install the foundationdb-server package for running a test fdbserver on your local device.
+This package is required to run the unit tests.
 
-[here for macOS]: https://apple.github.io/foundationdb/getting-started-mac.html
-[here for Linux]: https://apple.github.io/foundationdb/getting-started-linux.html
+## Usage
 
-### Bypassing dependency checks
+<!-- tabs-open -->
 
-When you execute a rebar command, erlfdb attempts to detect the version of the fdbcli
-installed on your system. If it cannot be detected, the rebar command is aborted.
+### Erlang's rebar3
 
-To disable the abort, use `ERLFDB_ASSERT_FDBCLI=0`. For example, you can safely use
-this for the `fmt` command, which does not do a compile action.
+Add erlfdb as a dependency in your Erlang project's rebar.config:
 
-```bash
-ERLFDB_ASSERT_FDBCLI=0 rebar3 fmt
+```erlang
+% rebar.config
+{deps, [
+    {erlfdb, "0.2.1"}
+]}.
 ```
 
-## Quick Example
+### Elixir's Mix
 
-A simple example showing how to open a database and read and write keys:
+Add erlfdb as a dependency in your Elixir project's mix.exs:
 
-```erlang
+```elixir
+# mix.exs
+defp deps do
+  [
+    {:erlfdb, "~> 0.2"}
+  ]
+end
+```
+
+<!-- tabs-close -->
+
+### Example
+
+A simple example showing how to open a database and read and write keys.
+
+See the [erlfdb Documentation](https://hexdocs.pm/erlfdb/erlfdb.html) for more.
 
-Eshell V9.3.3.6  (abort with ^G)
+<!-- tabs-open -->
+
+### Erlang
+
+```erlang
 1> Db = erlfdb:open(<<"/usr/local/etc/foundationdb/fdb.cluster">>).
 {erlfdb_database,#Ref<0.2859661758.3941466120.85406>}
 2> ok = erlfdb:set(Db, <<"foo">>, <<"bar">>).
@@ -59,8 +76,45 @@ ok
 not_found
 ```
 
+### Elixir
+
+```elixir
+iex> db = :erlfdb.open("/usr/local/etc/foundationdb/fdb.cluster")
+{:erlfdb_database, #Reference<0.2859661758.3941466120.85406>}
+iex> :ok = :erlfdb.set(db, "foo", "bar")
+:ok
+iex> :erlfdb.get(db, "foo")
+"bar"
+iex> :erlfdb.get(db, "bar")
+:not_found
+```
+
+<!-- tabs-close -->
+
 ## Binding Tester
 
 FoundationDB has a custom binding tester that can be used to test whether
 changes have broken compatibility. The GitHub Action runs the Binding Tester
 against the most recent supported version of FoundationDB.
+
+## Developing erlfdb
+
+### Building
+
+    $ rebar3 compile
+
+### Testing
+
+    # rebar3 eunit
+
+### Bypassing dependency checks
+
+When you execute a rebar command, erlfdb attempts to detect the version of the fdbcli
+installed on your system. If it cannot be detected, the rebar command is aborted.
+
+To disable the abort, use `ERLFDB_ASSERT_FDBCLI=0`. For example, you can safely use
+this for the `fmt` command, which does not do a compile action.
+
+```bash
+ERLFDB_ASSERT_FDBCLI=0 rebar3 fmt
+```

c_src/main.c

@@ -21,7 +21,7 @@
 #include "resources.h"
 #include "util.h"
 
-// FoundationDB can only be intiailized once
+// FoundationDB can only be initialized once
 // in a given OS process. By creating a random
 // atom we can flag whether erlfdb was previously
 // initialized in a given Erlang VM.

rebar.config

@@ -1,5 +1,13 @@
-{plugins, [{pc, "1.15.0"}]}.
-{project_plugins, [erlfmt, rebar3_ex_doc, rebar3_hex]}.
+{plugins, [
+    {pc, "1.15.0"}
+]}.
+
+{project_plugins, [
+    {erlfmt, "1.5.0"},
+    {rebar3_ex_doc, "0.2.24"},
+    {rebar3_hex, "7.0.8"}
+]}.
+
 {erlfmt, [write]}.
 {provider_hooks, [{pre, [{compile, {pc, compile}}, {clean, {pc, clean}}]}]}.
 {port_specs, [{"priv/erlfdb_nif.so", ["c_src/*.c"]}]}.

rebar.config.script

@@ -211,6 +211,7 @@ case MaxAPIVersion of
 end.
 
 ErlOpts = proplists:get_value(erl_opts, CONFIG, []).
+CONFIG1 = proplists:delete(erl_opts, CONFIG).
 
 [
     {erl_opts, ErlOpts ++ [{d, erlfdb_api_version, MaxAPIVersion}]},
@@ -254,4 +255,4 @@ ErlOpts = proplists:get_value(erl_opts, CONFIG, []).
             "$LDFLAGS /LIBPATH:\"c:/Program Files/foundationdb/lib/foundationdb\" fdb_c.lib"
         }
     ]}
-] ++ CONFIG.
+] ++ CONFIG1.