labs/lib/README.md

133 lines
4.7 KiB
Markdown

# Aux Lib
Aux Lib is intended to be a replacement for NixPkg's `lib` with stronger constraints around naming,
organization, and inclusion of functions. In addition to replacing library functions, Aux Lib also
defines a revamped version of the NixOS Module system intended to make it easier, more approachable,
and intuitive.
## Usage
The library can be imported both with and without Nix Flakes. To import the library using Nix Flakes,
add this repository as an input.
```nix
inputs.lib.url = "https://git.auxolotl.org/auxolotl/labs/archive/main.tar.gz?dir=lib";
```
To import the library without using Nix Flakes, you will need to use `fetchTarball` and import the
library entrypoint.
```nix
let
labs = builtins.fetchTarball {
url = "https://git.auxolotl.org/auxolotl/labs/archive/main.tar.gz";
sha256 = "<sha256>";
};
lib = import "${labs}/lib";
in
# ...
```
## Development
To contribute to the project, we accept pull requests to this repository. Please see the following
sections for information on the appropriate practices and required steps for working on Aux Lib.
### Documentation
We want our code to survive in the world, but without proper documentation that won't happen. In
order to not lose knowledge and also make it easier for others to begin participating in the
project we require that every function have an appropriate documentation comment. The format for
these comments is as follows:
```nix
let
## This is a description of what the function does. Any necessary information can be added
## here. After this point comes a gap before a Hindley-Milner style type signature. Note
## that these types are not actually checked, but serve as a helpful addition for the user
## in addition to being provided in generated documentation.
##
## @type Int -> String
func = x: builtins.toString x;
in
# ...
```
### Testing
All functions that are added to the project should include tests. The test suites are located
next to their implementation in files ending in `.test.nix`. These tests should ensure that
the library behaves as expected. The typical structure of these test suites is:
```nix
let
lib = import ./../default.nix;
in
{
"my function" = {
"test 1" = let
expected = 1;
input = {};
actual = lib.myFunction input;
in
actual == expected;
};
}
```
Successful tests will return `true` while failing test will resolve with `false`. You can run
all tests with the following command:
```shell
./test.sh
```
If you want to run a specific test suite, you can run the command, specifying the directory
to the tests file:
```shell
./test.sh $namespace
```
For example, to run the tests for only `attrs`, use the following command:
```shell
./test.sh attrs
```
### Formatting
> **Note:** To keep this flake light and keep its inputs empty we do not include a package
> set which would provide a formatter. Instead please run `nix run nixpkgs#nixfmt-rfc-style`
> until an improved solution is available.
All code in this project must be formatted using the provided formatter in the `flake.nix`
file. You can run this formatter using the command `nix fmt` (not currently available).
### Code Quality
In order to keep the project approachable and easy to maintain, certain patterns are not allowed.
In particular, the use of `with` and `rec` are not allowed. Additionally, you should prefer the
fully qualified name of a variable rather than creating intermediate ones using `inherit`.
### Adding Functionality
Before adding new features to the library, submit an issue or talk the idea over with one or
more of the project maintainers. We want to make sure that the library does not become bloated
with tools that aren't used. Some features may be better handled in a separate project. If you
do get the go-ahead to begin working on your feature, please place it in the library structure
similarly to how existing features are. For example, things dealing with strings should go in
`src/strings/default.nix`.
Additionally, you should prefer to group things in attribute sets for like-functionality. More
broad categories such as `strings` and `lists` are helpful, but scoped groups for things like
`into`, `from`, and `validate` also make the library more discoverable. Having all of the
different parts of the library mirroring this organizational structure makes building intuition
for working with the library much easier. To know when to group new things, consider the
following:
- Would your function name be multiple words like `fromString`?
- Are there multiple variants of this function?
- Would it be easier to find in a group?
- Would grouping help avoid name collisions or confusion?