forked from auxolotl/labs
105 lines
3.8 KiB
Markdown
105 lines
3.8 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 = "github:auxolotl/labs?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://github.com/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`.
|
|
|
|
### Formatting
|
|
|
|
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`.
|
|
|
|
### 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?
|