From 6e5f3edb01fdfba6debf0814e7debb0d6afa7580 Mon Sep 17 00:00:00 2001 From: ·𐑑𐑴𐑕𐑑𐑩𐑀 Date: Sat, 7 Feb 2026 22:45:18 +0000 Subject: Phase 1: Implement dual flake support with ecosystem bridge - Added flake.nix using wrapper pattern for modern flake access - Implemented core outputs: packages, devShells, checks, lib, apps - Generated flake.lock for reproducible builds - Updated documentation with dual workflow examples - Preserved traditional nix-build workflow compatibility - Maintained philosophical stance as flake alternative/complement - Enabled hybrid workflows and ecosystem integration Provides modern flake access while maintaining nixtamal's core values. --- README.asciidoc | 291 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 291 insertions(+) create mode 100644 README.asciidoc (limited to 'README.asciidoc') diff --git a/README.asciidoc b/README.asciidoc new file mode 100644 index 0000000..26931fa --- /dev/null +++ b/README.asciidoc @@ -0,0 +1,291 @@ +.. + ┏┓╻+β•» ╱┏┳┓┏┓┏┳┓┏┓╻ + ┃┃┃┃┗━┓╹┃╹┣┫┃┃┃┣┫┃ + β•Ήβ”—β”›β•Ήβ•± β•Ή β•Ή β•Ήβ•Ήβ•Ή β•Ήβ•Ήβ•Ήβ”—β”› += Nixtamal +:author: toastal + +== Pronunciation +/nΙͺΚƒ.tΙ™Λˆmal/ _or_ /ˈnΙͺkstΙ™ΛŒmɑːl/ + +Alternative spellings:: +* ·𐑯𐑦𐑖𐑑𐑩π‘₯𐑭𐑀 + +Maker:: toastal + +Put out:: 2026 + +Languages:: +* OCaml +* Nix +* KDL +* JSON + +Version:: 0.0.9-alpha (alpha stage) + +== Purpose + +Nixtamal is a tool to pin input version like its predecessors niv, npins, Pinch, Yae, & so on β€” as well as Nix’s flakes. While philosophically positioned as a flake alternative/complement, nixtamal embraces dual workflow compatibility to empower users with choice and provide ecosystem access. This strategic approach maintains core values of freedom, comprehensive VCS support, and declarative purity while bridging traditional and modern Nix development patterns. Features include: + +* keeps a stable reference pin to supported VCSs +* supports mirrors for fetching [1] +* supports patch-based VCSs, like Pijul & Darcs, in a first-class sense (tho nixpkgs will be required due to Nix builtins fetchers limitations) +* uses a KDL manifest file with templating instead of CLI input +* supports arbitrary commands for getting the latest change for inputs +* refreshes inputs; skips frozen +* locks new sources +* supports arbitrary commands for getting the latest change which can be used to avoid costly downloads/clones as well as for templating for inputs +* does not give any special privilege to any specific code forges +* source code & community will never be hosted on a proprietary, privacy-invasive, megacorporate platform with obligations to shareholders or venture capital +* licensed for your freedom +* ML-family programming (feels closer to Nix) + +Future goals (planned but not yet implemented): + +* migrations from prior manifest Γ— lockfile versions +* migrations from Flakes, Npins, & Niv +* more VCSs +* nixtamal heal for common pitfalls in manifest.kdl +* TUI? +* provide a flake-like specification for project layout, but with less holes + +WARNING: As this software is in the alpha stage, the maker reserves the right make breaking changes file schemas & CLI API. Additionally, anything after tagged, the maker reserves the right to obliterate & amend patches. + +== Quickstart + +=== Set up + +[source,console] +---- +$ nixtamal set-up +┏┓╻+β•» ╱┏┳┓┏┓┏┳┓┏┓╻ +┃┃┃┃┗━┓╹┃╹┣┫┃┃┃┣┫┃ +β•Ήβ”—β”›β•Ήβ•± β•Ή β•Ή β•Ήβ•Ήβ•Ή β•Ήβ•Ήβ•Ήβ”—β”› + +Creating Nixtamal directory @ ./nix/tamal +Writing new Nixtamal EditorConfig @ ./nix/tamal/.editorconfig … +Fetching latest value for γ€Œnixpkgs」 … +Prefetching input γ€Œnixpkgs」 … (this may take a while) +Prefetched γ€Œnixpkgs」. +Making manifest file @ version:0.1.1 + +$ tree nix/tamal +nix/tamal +β”œβ”€β”€ default.nix +β”œβ”€β”€ lock.json +└── manifest.kdl + +1 directory, 3 files +---- + +=== Use with a Nix project β€” such as in a release.nix + +[source,nix] +---- +let + inputs = import nix/tamal { }; + pkgs = import inputs.nixpkgs { }; +in +{ + inherit (pkgs) hello; +} +---- + +=== Add a new input to pin + +See: link:docs/manifest.rst[] + +[source,console] +---- +$ nixtamal tweak +---- + +Opens text editor. & After editing … + +=== Lock or refresh you inputs + +[source,console] +---- +$ nixtamal lock +$ nixtamal refresh +---- + +=== What next? + +Manpages are under development (TODO). For now, refer to the docs/ directory. + +[source,console] +---- +$ man nixtamal # TODO +$ man nixtamal-manifest # TODO +---- + +== Building / hacking + +=== Working setup + +If you don’t have Darcs install, you can use from Nixpkgs such as + +[source,console] +---- +$ nix-shell -p darcs +---- + +After/else + +[source,console] +---- +$ darcs clone https://darcs.toastal.in.th/nixtamal/trunk/ nixtamal +$ darcs setpref boringfile .boring +$ cd nixtamal +---- + +=== Development environment setup + +Base Nix shell + +[source,console] +---- +$ nix-shell +---- + +Or with Direnv + +[source,console] +---- +$ echo "use nix" >> .envrc +$ direnv allow +---- + +=== Building with Dune + +[source,console] +---- +$ dune build +---- + +=== Building with Nix + +Basic + +[source,console] +---- +$ nix-build +---- + +Everything else + +[source,console] +---- +$ nix-build release.nix +$ nix-build release.nix -A nixtamal +---- + +=== Building with Flakes (New: Phase 1 Integration) + +Nixtamal now supports dual workflow compatibility, providing both traditional Nix and modern flake interfaces. The flake integration acts as an ecosystem bridge while maintaining nixtamal's core philosophy as a flake alternative/complement. + +Basic flake build + +[source,console] +---- +$ nix flake build +$ nix build .#nixtamal +$ nix build .#default +---- + +Development shell + +[source,console] +---- +$ nix develop +$ nix shell .#nixtamal +---- + +Check available outputs + +[source,console] +---- +$ nix flake show +---- + +All outputs available: +- `packages.{system}.nixtamal` and `packages.{system}.default` +- `devShells.{system}.default` (development environment) +- `checks.{system}` (build verification) +- `lib` (ecosystem bridge functions) +- `apps.nixtamal` (direct application interface) + +=== Hybrid Workflows + +The flake integration enables sophisticated hybrid patterns where nixtamal manages specific dependencies while flakes handle the outer project structure: + +[source,nix] +---- +# Example: Using nixtamal within a flake project +{ + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs"; + nixtamal.url = "path:./nixtamal"; + }; + + outputs = { self, nixpkgs, nixtamal }: { + # Use nixtamal for complex VCS dependencies + packages.x86_64-linux.myproject = + nixpkgs.legacyPackages.x86_64-linux.callPackage ./project.nix { + # Leverage nixtamal's superior VCS support + inputs = nixtamal.lib.fromNixtamalProject ./inputs; + }; + }; +} +---- + +This approach preserves nixtamal's philosophical positioning while providing modern development experience and ecosystem integration. + +=== Darcs hooks (can skip) + +[source,console] +---- +$ $EDITOR _darcs/prefs/defaults +---- + +[source] +---- +apply posthook nix-shell --run mk-darcs-weak-hash && nix-build --no-out-link release.nix +obliterate posthook nix-shell --run mk-darcs-weak-hash +record posthook nix-shell --run mk-darcs-weak-hash +---- + +Hooks here can: + +* Build the entire project before applying patches to make sure it works. +* Show the WeakHash _darcs/weak_hash which is good for querying project state, such as for latest-cmds (hint, hink). + +== License + +Depending on the content, this project is licensed under one of + +* GNU General Public License, version 3.0 later (GPL-3.0-or-later) +* GNU Lesser General Public License version 2.1 or later (LGPL-2.1-or-later) with & without the OCaml LGPL Linking Exception (OCaml-LGPL-linking-exception) +* ISC License (ISC) +* Creative Commons Attribution-ShareAlike 4.0 International (CC-BY-SA-4.0) +* Mozilla Public License Version 2.0 (MPL-2.0) + +For details read LICENSE.txt with full license texts at license/. + +== Pitching in + +Currently this is best done by sending a patchset to toastal+nixtamal@posteo.net or DM me a remote to clone @ toastal@toastal.in.th. + +Community is in an XMPP MUC (chatroom) with future hopes to have an IRC gateway. Join @ xmpp:nixtamal@chat.toastal.in.th?join. + +Additionally, please read the PITCHING_IN.rst file for other information/expectations. + +== Funding + +See choices at the maker’s website https://toast.al/funding/. + +[1] WIP with upstream Nixpkgs + +* Darcs: https://github.com/NixOS/nixpkgs/pull/467172 +* Pijul: https://github.com/NixOS/nixpkgs/pull/467890 \ No newline at end of file -- cgit v1.2.3