path: root/README.asciidoc

```
	┏┓╻+╻ ╱┏┳┓┏┓┏┳┓┏┓╻
	┃┃┃┃┗━┓╹┃╹┣┫┃┃┃┣┫┃
	╹┗┛╹╱ ╹ ╹ ╹╹╹ ╹╹╹┗┛
```
:author: toastal

== Pronunciation
/nɪks.təˈmal/ ("nix-tamal")

Maker:: toastal
Website:: https://nixtamal.tech (launching soon)

Put out:: 2026

Languages::
* OCaml
* Nix
* KDL
* JSON

Version:: 1.1-alpha (alpha stage)

**Community-maintained fork**: Addressing the original project's lack of reasonable maintenance, this fork prioritizes long-term maintainability, compatibility, and active development.

*Original project:* link:https://darcs.toastal.in.th/nixtamal/trunk/[darcs.toastal.in.th/nixtamal/trunk]

== 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, & Fossil, 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)
* supports schema versioning for manifests and lockfiles

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.

== Ongoing Integrations

Nixtamal is being extended to support additional frameworks and tools:

=== Nilla Framework

https://github.com/nilla-nix/nilla[Nilla] is a Nix framework with loaders and module system. Nixtamal provides first-class support for Nilla inputs, including manifest serialization, lockfile integration, and prefetch functionality.

[source,kdl]
----
my-input {
    nilla {
        repository "https://github.com/user/nilla-project.git"
        branch "main"
        path "./nilla.nix"
    }
}
----

Attributes:
* `repository` - Git repository URL (templated)
* `mirrors` - Repository mirrors (optional, templated)
* `branch` or `ref` - Git reference point
* `path` - Path to nilla.nix (defaults to `./nilla.nix`)

Nixtamal prefetch validates that the nilla.nix file exists at the specified path within the fetched repository. The implementation uses standard nix prefetch tooling for consistency and reliability.

== 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
$ nixtamal upgrade
----

=== 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 with flake-parts)

Flakes use Determinate Nix and nixpkgs (github:DeterminateSystems/nix, NixOS/nixpkgs/nixos-unstable-small) for strong community support for Nix creator Eelco Dolstra's vision.

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.

Website: https://nixtamal.tech

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