aboutsummaryrefslogtreecommitdiff
path: root/doc/manual/src/contributing
AgeCommit message (Collapse)Author
2024-04-22meson: flip the switch!!Qyriad
This commit makes Meson the default buildsystem for Lix. The Make buildsystem is now deprecated and will be removed soon, but has not yet, which will be done in a later commit when all seems good. The mesonBuild jobs have been removed, and have not been replaced with equivalent jobs to ensure the Make buildsystem still works. The full, new commands in a development shell are: $ meson setup ./build "--prefix=$out" $mesonFlags (A simple `meson setup ./build` will also build, but will do a different thing, not having the settings from package.nix applied.) $ meson compile -C build $ meson test -C build --suite=check $ meson install -C build $ meson test -C build --suite=installcheck (Check and installcheck may both be done after install, allowing you to omit the --suite argument entirely, but this is the order package.nix runs them in.) If tests fail and Meson helpfully has no output for why, use the `--print-error-logs` option to `meson test`. Why this is not the default I cannot explain. If you change a setting in the buildsystem, most cases will automatically regenerate the Meson configuration, but some cases, like trying to build a specific target whose name is new to the buildsystem (e.g. `meson compile -C build src/libmelt/libmelt.dylib`, when `libmelt.dylib` did not exist as a target the last time the buildsystem was generated), then you can reconfigure using new settings but existing options, and only recompiling stuff affected by the changes: $ meson setup --reconfigure build Note that changes to the default values in `meson.options` or in the `default_options :` argument to project() are NOT propagated with `--reconfigure`. If you want a totally clean build, you can use: $ meson setup --wipe build That will work regardless of if `./build` exists or not. Specific, named targets may be addressed in `meson build -C build <target>` with the "target ID" if there is one, which is the first string argument passed to target functions that have one, and unrelated to the variable name, e.g.: libexpr_dylib = library('nixexpr', …) can be addressed with: $ meson compile -C build nixexpr All targets may be addressed as their output, relative to the build directory, e.g.: $ meson compile -C build src/libexpr/libnixexpr.so But Meson does not consider intermediate files like object files targets. To build a specific object file, use Ninja directly and specify the output file relative to the build directory: $ ninja -C build src/libexpr/libnixexpr.so.p/nixexpr.cc.o To inspect the canonical source of truth on what the state of the buildsystem configuration is, use: $ meson introspect Have fun! Change-Id: Ia3e7b1e6fae26daf3162e655b4ded611a5cd57ad
2024-04-11docs: redo content generation for mdbook and manualeldritch horrors
manpages can be rendered using the markdown output of mdbook, the rest of the manual can generated out of the main doc/manual source tree. we still use lowdown to actually render manpages instead of eg mdbook-man because lowdown does generate reasonably good manpages (though that is also somewhat debatable, but they're a lot better than mdbook-man). doing this not only lets us drastically simplify the lowdown pipeline, but also remove all custom {{#include}} handling since now mdbook does all of it, even for the manpage builds. even the lowdown wrapper isn't entirely necessary because lowdown can take all wrapper arguments with command line flags rather than bits of input file content. This also implements running mdbook in Meson, in order to generate the manpages. The mdbook outputs are also installed in the usual location. Co-authored-by: Qyriad <qyriad@qyriad.me> Change-Id: I60193f9fd0f15d48872f071af35855cda2a0f40b
2024-03-29Add `pre-commit` checksRebecca Turner
The big ones here are `trim-trailing-whitespace` and `end-of-file-fixer` (which makes sure that every file ends with exactly one newline character). Change-Id: Idca73b640883188f068f9903e013cf0d82aa1123
2024-03-27build: replace changelog-d with local scripteldritch horrors
hacking changelog-d to support not just github but also forgejo and gerrit is a lot more complicated than it's worth, even moreso since the entire thing can just as well be done with ~60 lines of python. this new script is also much cheaper to instantiate (being python), so having it enabled in all shells is far less of a hassle. we've also adjusted existing release notes that referenced a gerrit cl to auto-link to the cl in question, making the diff a bit bigger closes https://git.lix.systems/lix-project/lix/issues/176 Change-Id: I8ba7dd0070aad9ba4474401731215fcf5d9d2130
2024-03-04Merge pull request #9692 from 9999years/update-clang-stdenveldritch horrors
Remove `clang11Stdenv` (cherry picked from commit cbf99c71c6f58579174c1c7649a5421c1d2ba9b0) Change-Id: I716ce1a54f2006c4a9dc9716e8529fe7858ecebb
2024-03-04Merge pull request #9573 from hercules-ci/rl-next-md-frontmattereldritch horrors
rl-next: Fix and support markdown frontmatter syntax (cherry picked from commit 69b7876a0810269ad71807594cfd99b26cd8a5ff) Change-Id: I8bfb8967af0943080fdd70d257c34abaf0a9fedf
2024-03-04Merge pull request #9465 from obsidiansystems/build-direldritch horrors
Use `buildprefix` in a few more places (cherry picked from commit b6a3fde6b7a416929553e6be36fc991680ddf9ef) Change-Id: I2790663fa9f8242ac2db6582b7e421d2fdf42942
2024-03-04Merge pull request #9393 from hercules-ci/changelog-deldritch horrors
Automatically compile hand-written release notes with `changelog-d` (cherry picked from commit 928f0c13414d20c1af88b30bd6700fd730ee0bab) Change-Id: Ia0685835c52edf185b64dd696b19305746c077e5
2024-03-04Merge pull request #9131 from obsidiansystems/delete-bootstrap-scripteldritch horrors
Get rid of `bootstrap.sh` (cherry picked from commit aaef47a08eaf54a8856dd25c784fd85d8d7b0e22) Change-Id: I1a74bed0c23d6fda06d5dfd8ecad443b9122da12
2024-03-04Merge pull request #8923 from obsidiansystems/test-protoeldritch horrors
Unit test some worker protocol serializers (cherry picked from commit c6faef61a6f31c71146aee5d88168e861df9a22a) Change-Id: I99e36f5f17eb7642211a4e42a16b143424f164b4
2023-12-01Move tests to separate directories, and documentJohn Ericson
Today, with the tests inside a `tests` intermingled with the corresponding library's source code, we have a few problems: - We have to be careful that wildcards don't end up with tests being built as part of Nix proper, or test headers being installed as part of Nix proper. - Tests in libraries but not executables is not right: - It means each executable runs the previous unit tests again, because it needs the libraries. - It doesn't work right on Windows, which doesn't want you to load a DLL just for the side global variable . It could be made to work with the dlopen equivalent, but that's gross! This reorg solves these problems. There is a remaining problem which is that sibbling headers (like `hash.hh` the test header vs `hash.hh` the main `libnixutil` header) end up shadowing each other. This PR doesn't solve that. That is left as future work for a future PR. Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io> (cherry picked from commit 91b6833686a6a6d9eac7f3f66393ec89ef1d3b57) (cherry picked from commit a61e42adb528b3d40ce43e07c79368d779a8b624)
2023-12-01Put functional tests in `tests/functional`John Ericson
I think it is bad for these reasons when `tests/` contains a mix of functional and integration tests - Concepts is harder to understand, the documentation makes a good unit vs functional vs integration distinction, but when the integration tests are just two subdirs within `tests/` this is not clear. - Source filtering in the `flake.nix` is more complex. We need to filter out some of the dirs from `tests/`, rather than simply pick the dirs we want and take all of them. This is a good sign the structure of what we are trying to do is not matching the structure of the files. With this change we have a clean: ```shell-session $ git show 'HEAD:tests' tree HEAD:tests functional/ installer/ nixos/ ``` (cherry picked from commit 68c81c737571794f7246db53fb4774e94fcf4b7e)
2023-08-29docs/testing: point out the existence of `GTEST_FILTER` (#8883)Cole Helbling
2023-07-20fix broken links (#8722)Valentin Gagarin
2023-07-19Merge pull request #8680 from NixLayeredStore/test-groupsJohn Ericson
Introduce notion of a test group, use for CA tests
2023-07-19do not mention output attributesValentin Gagarin
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
2023-07-19note that naming convention is from AutotoolsValentin Gagarin
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
2023-07-19expand on the system type in hacking guideValentin Gagarin
2023-07-18Introduce notion of a test group, use for CA testsJohn Ericson
Grouping our tests should make it easier to understand the intent than one long poorly-arranged list. It also is convenient for running just the tests for a specific component when working on that component. We need at least one test group so this isn't dead code; I decided to collect the tests for the `ca-derivations` and `dynamic-derivations` experimental features in groups. Do ```bash make ca.test-group -jN ``` and ```bash make dyn-drv.test-group -jN ``` to try running just them. I originally did this as part of #8397 for being able to just the local overlay store alone. I am PRing it separately now so we can separate general infra from new features. Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-07-11Expanded test suiteMathnerd314
* Lang now verifies errors and parse output * Some new miscellaneous tests * Easy way to update the tests * Document workflow in manual * Use `!` not `~` as separater char for sed It is confusing to use `~` when we are talking about paths and home directories! * Test test suite itself (`test/lang-test/infra.sh`) Additionally, run shellcheck on `tests/lang.sh` to help ensure it is correct, now that is is more complex. Co-authored-by: Robert Hensing <roberth@users.noreply.github.com> Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-06-27Split testing into its own page in the contribution guideJohn Ericson
`hacking.md` has gotten really big!
2023-06-21do not use "target", as it's a loaded term in the domain of compilersValentin Gagarin
Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
2023-06-21fix anchor linkValentin Gagarin
2023-06-20use more self-descriptive section headingsValentin Gagarin
2023-06-19Split out worker protocol template definitions from declarationsJohn Ericson
This is generally a fine practice: Putting implementations in headers makes them harder to read and slows compilation. Unfortunately it is necessary for templates, but we can ameliorate that by putting them in a separate header. Only files which need to instantiate those templates will need to include the header with the implementation; the rest can just include the declaration. This is now documenting in the contributing guide. Also, it just happens that these polymorphic serializers are the protocol agnostic ones. (Worker and serve protocol have the same logic for these container types.) This means by doing this general template cleanup, we are also getting a head start on better indicating which code is protocol-specific and which code is shared between protocols.
2023-06-17Fix wikipedia links (#8533)Christina Sørensen
2023-05-17Convert short nix options to long onesAlexander Schmolck
e.g. nix-env -e subversion => nix-env --uninstall subversion The aim is to make the documentation less cryptic for newcomers and the long options are more self-documenting. The change was made with the following script: <https://github.com/aschmolck/convert-short-nix-opts-to-long-ones> and sanity checked visually.
2023-04-09Single page for experimental feature descriptionsJohn Ericson
As requested by @fricklerhandwerk.
2023-04-06Document the concept of “experimental feature” (#5930)Théophane Hufschmitt
Add a page explaining what “experimental features” are, when and how they should be used Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io> Co-authored-by: Eelco Dolstra <edolstra@gmail.com> Co-authored-by: John Ericson <John.Ericson@Obsidian.Systems>
2023-03-21Add links to API docs / coverage analysis to the hacking sectionEelco Dolstra
2023-02-28doc/cli-guideline: Improve examples Robert Hensing
Turns out that the settings themselves have a bad data model anyway, so we cut that. They do still occur in the first example, but not in focus.
2023-02-28doc/cli-guideline: Apply suggestions from code reviewRobert Hensing
Thanks Valentin!
2023-02-28doc/cli-guideline: Add JSON guidelineRobert Hensing
2023-02-20Merge pull request #7867 from NixOS/hacking-crossRobert Hensing
doc/hacking.md: Corrections and additions for cross
2023-02-20doc/hacking.md: Corrections and additions for crossRobert Hensing
2023-02-20Nix's own flake: Dedup and memoize moreJohn Ericson
- `nixpkgsFor` does all of native, static, cross, and the different stdenvs. - The main Nix derivation is no longer duplicated for static. - DRY nixpkgs.lib and lib.genAttrs calls.
2023-02-13Improve hacking.mdYorick van Pelt
- Refer to current version in readme - Split into flakes and non-flakes section - Change order to move nix-build to the end, since people often start with it in the beginning. - Use proper "Note" syntax - Add notes about editor integration - Move information about target platforms and stdenvs into separate sections Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io> Co-authored-by: Alexander Bantyev <alexander.bantyev@tweag.io> Co-authored-by: Théophane Hufschmitt <theophane.hufschmitt@tweag.io>
2023-02-07Make install command in documentation compatible with fish shell (#7474)David Dunn
Use a pipe for all install commands Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-02-05fix `clang11Stdenv` dev shell documentationPeter Becich
`clang11StdenvPackages` does not exist ``` │ └───x86_64-linux │ ├───ccacheStdenv: development environment 'nix' │ ├───clang11Stdenv: development environment 'nix' │ ├───clangStdenv: development environment 'nix' │ ├───default: development environment 'nix' │ ├───gccStdenv: development environment 'nix' │ ├───libcxxStdenv: development environment 'nix' │ └───stdenv: development environment 'nix' ```
2023-01-23Add `rapidcheck` dependency for testingJohn Ericson
Property tests are great! Co-authored-by: Cole Helbling <cole.e.helbling@outlook.com>
2023-01-10doc/manual/src/contributing/hacking.md: Apply suggestionRobert Hensing
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-01-10doc/manual/hacking: Document @docroot@ variableRobert Hensing
2023-01-10doc/manual: Apply suggestions from code reviewRobert Hensing
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2023-01-10doc/manual: Document hacking on the manual linksRobert Hensing
2022-12-23Apply suggestions from code reviewJohn Ericson
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2022-12-21Make `./mk/run-test.sh` work by itself; add `mk/debug-test.sh`John Ericson
First, logic is consolidated in the shell script instead of being spread between them and makefiles. That makes understanding what is going on a little easier. This would not be super interesting by itself, but it gives us a way to debug tests more easily. *That* in turn I hope is much more compelling. See the updated manual for details. Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io> Co-authored-by: Eelco Dolstra <edolstra@gmail.com> Co-authored-by: Robert Hensing <roberth@users.noreply.github.com>
2022-10-05Merge pull request #6652 from abathur/doc_install_testsValentin Gagarin
2022-10-05Apply suggestions from code reviewTravis A. Everett
Co-authored-by: Valentin Gagarin <valentin.gagarin@tweag.io>
2022-09-23add ccacheStdenvSolène Rapenne
when using ccache, rebuild time has been measured 89% faster while not slowing the speed of cold builds
2022-09-18address review feedbackTravis A. Everett
Mainly: - Try to triangulate between narrative that framed this as a new/easy process and the need for a reference that will not quickly grow stale. - Fix a ~continuity issue where the text was talking about "your Cachix cache" before saying that you'd need to make a Cachix cache to enable the installer tests. - Adopt suggestion on titling, and nest subtitles in the installer test section.