From b3ed697b798cd7acfd3789c4b36e9999e360b1a4 Mon Sep 17 00:00:00 2001 From: Tom Aylott Date: Thu, 18 Sep 2025 19:02:40 -0400 Subject: [PATCH 1/7] Add AGENTS.md file This commit adds the AGENTS.md file, which contains guidelines for contributing to the project. This includes information on project structure, build and test commands, coding style, testing guidelines, and commit/pull request guidelines. --- AGENTS.md | 28 ++++++++++++++++++++++++++++ CLAUDE.md | 1 + 2 files changed, 29 insertions(+) create mode 100644 AGENTS.md create mode 120000 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..dec89dc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,28 @@ +# Repository Guidelines + +## Project Structure & Module Organization +libansilove is a C library that converts ANSI and related art files to PNG. Core headers live in `include/`, while the implementation sits in `src/` with `loaders/` containing format-specific decoders and `fonts/` bundling built-in typefaces. Cross-platform fallbacks are under `compat/`. The `example/` directory shows how to invoke the API end-to-end, and `man/` provides installed manual pages. Dedicated fuzzing harnesses reside in `fuzz/`; build them only when running sanitizer-heavy tests. + +## Build, Test, and Development Commands +- `cmake -S . -B build -DCMAKE_BUILD_TYPE=Release`: configure the project after installing GD headers and libs. +- `cmake --build build`: compile shared and static variants of the library. +- `cmake --build build --target install`: install artifacts into the default prefix. +- `cmake -S fuzz -B fuzz-build`: set up clang-based libFuzzer targets. +- `cmake --build fuzz-build`: produce fuzz binaries such as `ansi` and `tundra`. + +## Coding Style & Naming Conventions +- Target C99 with the default warning set (`-Wall -Wextra -pedantic`). +- Indent with tabs for blocks; align wrapped parameters using spaces as needed, and avoid trailing whitespace. +- Public APIs stay in `include/ansilove.h` and use the `ansilove_*` prefix; internal helpers remain lowercase with underscores and `static` linkage. +- Mirror existing filenames (`loadfile.c`, `savefile.c`) when adding new modules or loaders. + +## Testing Guidelines +- There is no unit-test harness; validate behavior with the example app and fuzzers. +- After building, run `build/example/ansilove_example ` to confirm PNG output. +- For fuzzing, execute `./fuzz-build/ansi -runs=10000 corpus/` (seed the corpus with representative art files). Investigate sanitizer reports immediately and add reproducer samples. +- Ensure new formats or options ship with updated example inputs or fuzz seeds that exercise the paths. + +## Commit & Pull Request Guidelines +- Commit messages follow sentence case with concise statements ending in a period (for example, `Update ChangeLog.`). +- Keep functional changes and formatting adjustments in separate commits and ensure files build before pushing. +- Pull requests should summarize the change, call out impacted loaders, and link tracking issues. Note which build or fuzz commands were run, and attach PNG outputs or screenshots when visual diffs help reviewers. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 0000000..47dc3e3 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENTS.md \ No newline at end of file From 0308363e77734c364e1eaa238e7134ad7f1f4142 Mon Sep 17 00:00:00 2001 From: Tom Aylott Date: Thu, 18 Sep 2025 19:03:59 -0400 Subject: [PATCH 2/7] Add flake.nix for Nix development environment Introduces a flake.nix file to manage the development environment for libansilove using Nix Flakes. This includes defining packages and a development shell with necessary build tools and libraries. --- .envrc | 1 + flake.nix | 56 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) create mode 100644 .envrc create mode 100644 flake.nix diff --git a/.envrc b/.envrc new file mode 100644 index 0000000..3550a30 --- /dev/null +++ b/.envrc @@ -0,0 +1 @@ +use flake diff --git a/flake.nix b/flake.nix new file mode 100644 index 0000000..003b959 --- /dev/null +++ b/flake.nix @@ -0,0 +1,56 @@ +{ + description = "Development environment for libansilove"; + + inputs = { + nixpkgs.url = "github:NixOS/nixpkgs/nixos-24.05"; + flake-utils.url = "github:numtide/flake-utils"; + }; + + outputs = { self, nixpkgs, flake-utils }: + flake-utils.lib.eachDefaultSystem (system: + let + pkgs = import nixpkgs { inherit system; }; + version = "1.4.2"; + in { + packages.default = pkgs.stdenv.mkDerivation { + pname = "libansilove"; + inherit version; + src = ./.; + nativeBuildInputs = [ + pkgs.cmake + pkgs.pkg-config + ]; + buildInputs = [ + pkgs.libgd + ]; + cmakeFlags = [ + "-DCMAKE_BUILD_TYPE=Release" + ]; + meta = with pkgs.lib; { + description = "Library to convert ANSI and artscene formats to PNG"; + homepage = "https://www.ansilove.org"; + license = licenses.bsd2; + maintainers = []; + platforms = platforms.unix; + }; + }; + + devShells.default = pkgs.mkShell { + packages = [ + pkgs.cmake + pkgs.ninja + pkgs.pkg-config + pkgs.libgd + pkgs.clang + pkgs.clang-tools + pkgs.gdb + ]; + shellHook = '' + export CC=${pkgs.clang}/bin/clang + export CXX=${pkgs.clang}/bin/clang++ + echo "libansilove dev shell loaded." + ''; + }; + } + ); +} From cfebe513910a28cd5f66a628ade0df88861f05a2 Mon Sep 17 00:00:00 2001 From: Tom Aylott Date: Thu, 18 Sep 2025 19:04:27 -0400 Subject: [PATCH 3/7] Refactor flake.nix for readability --- flake.nix | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/flake.nix b/flake.nix index 003b959..9907316 100644 --- a/flake.nix +++ b/flake.nix @@ -6,10 +6,14 @@ flake-utils.url = "github:numtide/flake-utils"; }; - outputs = { self, nixpkgs, flake-utils }: - flake-utils.lib.eachDefaultSystem (system: - let - pkgs = import nixpkgs { inherit system; }; + outputs = { + self, + nixpkgs, + flake-utils, + }: + flake-utils.lib.eachDefaultSystem ( + system: let + pkgs = import nixpkgs {inherit system;}; version = "1.4.2"; in { packages.default = pkgs.stdenv.mkDerivation { From d64a8bac22087122ef1451f2302b630dea9e0a26 Mon Sep 17 00:00:00 2001 From: Tom Aylott Date: Thu, 18 Sep 2025 19:05:16 -0400 Subject: [PATCH 4/7] Add flake.lock file This commit introduces the `flake.lock` file, which pins the exact versions of the dependencies used by the Nix flake. This ensures reproducible builds by locking down the revisions of `nixpkgs`, `flake-utils`, and `nix-systems`. --- flake.lock | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) create mode 100644 flake.lock diff --git a/flake.lock b/flake.lock new file mode 100644 index 0000000..2468070 --- /dev/null +++ b/flake.lock @@ -0,0 +1,61 @@ +{ + "nodes": { + "flake-utils": { + "inputs": { + "systems": "systems" + }, + "locked": { + "lastModified": 1731533236, + "narHash": "sha256-l0KFg5HjrsfsO/JpG+r7fRrqm12kzFHyUHqHCVpMMbI=", + "owner": "numtide", + "repo": "flake-utils", + "rev": "11707dc2f618dd54ca8739b309ec4fc024de578b", + "type": "github" + }, + "original": { + "owner": "numtide", + "repo": "flake-utils", + "type": "github" + } + }, + "nixpkgs": { + "locked": { + "lastModified": 1735563628, + "narHash": "sha256-OnSAY7XDSx7CtDoqNh8jwVwh4xNL/2HaJxGjryLWzX8=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "b134951a4c9f3c995fd7be05f3243f8ecd65d798", + "type": "github" + }, + "original": { + "owner": "NixOS", + "ref": "nixos-24.05", + "repo": "nixpkgs", + "type": "github" + } + }, + "root": { + "inputs": { + "flake-utils": "flake-utils", + "nixpkgs": "nixpkgs" + } + }, + "systems": { + "locked": { + "lastModified": 1681028828, + "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=", + "owner": "nix-systems", + "repo": "default", + "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e", + "type": "github" + }, + "original": { + "owner": "nix-systems", + "repo": "default", + "type": "github" + } + } + }, + "root": "root", + "version": 7 +} From 695c512c86b08e6a75543fabebba6f7b147da3db Mon Sep 17 00:00:00 2001 From: Tom Aylott Date: Thu, 18 Sep 2025 19:09:32 -0400 Subject: [PATCH 5/7] Refactor: Use gd instead of libgd Updates the flake.nix to use the `gd` package instead of the deprecated `libgd`. Also conditionally adds `gdb` for non-Darwin systems and `lldb` for Darwin systems. --- flake.nix | 26 ++++++++++++++++---------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/flake.nix b/flake.nix index 9907316..64795ac 100644 --- a/flake.nix +++ b/flake.nix @@ -25,7 +25,7 @@ pkgs.pkg-config ]; buildInputs = [ - pkgs.libgd + pkgs.gd ]; cmakeFlags = [ "-DCMAKE_BUILD_TYPE=Release" @@ -40,15 +40,21 @@ }; devShells.default = pkgs.mkShell { - packages = [ - pkgs.cmake - pkgs.ninja - pkgs.pkg-config - pkgs.libgd - pkgs.clang - pkgs.clang-tools - pkgs.gdb - ]; + packages = + [ + pkgs.cmake + pkgs.ninja + pkgs.pkg-config + pkgs.gd + pkgs.clang + pkgs.clang-tools + ] + ++ pkgs.lib.optionals (!pkgs.stdenv.isDarwin) [ + pkgs.gdb + ] + ++ pkgs.lib.optionals pkgs.stdenv.isDarwin [ + pkgs.lldb + ]; shellHook = '' export CC=${pkgs.clang}/bin/clang export CXX=${pkgs.clang}/bin/clang++ From af32bf3cb1265f8f54b51e2a72bf8bb2a6a2c7fc Mon Sep 17 00:00:00 2001 From: Tom Aylott Date: Thu, 18 Sep 2025 19:15:40 -0400 Subject: [PATCH 6/7] Add Nix and direnv ignores to .gitignore --- .gitignore | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.gitignore b/.gitignore index 131152d..1659e4d 100644 --- a/.gitignore +++ b/.gitignore @@ -6,6 +6,13 @@ # build products build/ +# Nix +result +result-*/ + +# direnv +.direnv/ + # CMake CMakeFiles CMakeCache.txt From 3bc03666a16325560425e09506b4ffe9da0763d0 Mon Sep 17 00:00:00 2001 From: Tom Aylott Date: Thu, 18 Sep 2025 19:23:13 -0400 Subject: [PATCH 7/7] Add Nix flake instructions Include commands for entering the dev shell, building, and checking the flake. Also add a note about updating the flake.lock file. --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index dec89dc..086b1e4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -9,6 +9,9 @@ libansilove is a C library that converts ANSI and related art files to PNG. Core - `cmake --build build --target install`: install artifacts into the default prefix. - `cmake -S fuzz -B fuzz-build`: set up clang-based libFuzzer targets. - `cmake --build fuzz-build`: produce fuzz binaries such as `ansi` and `tundra`. +- `nix develop`: enter the flake-backed dev shell with clang, pkg-config, GD, and platform-appropriate debugger preinstalled. +- `nix build`: build the default flake package (shared/static library) without touching your host toolchain. +- `nix flake check`: validate the flake packages and dev shell evaluate cleanly across supported systems. ## Coding Style & Naming Conventions - Target C99 with the default warning set (`-Wall -Wextra -pedantic`). @@ -21,6 +24,7 @@ libansilove is a C library that converts ANSI and related art files to PNG. Core - After building, run `build/example/ansilove_example ` to confirm PNG output. - For fuzzing, execute `./fuzz-build/ansi -runs=10000 corpus/` (seed the corpus with representative art files). Investigate sanitizer reports immediately and add reproducer samples. - Ensure new formats or options ship with updated example inputs or fuzz seeds that exercise the paths. +- If you touch the flake, rerun `nix build` and `nix flake check` and commit the updated `flake.lock` (keep changes reproducible). ## Commit & Pull Request Guidelines - Commit messages follow sentence case with concise statements ending in a period (for example, `Update ChangeLog.`).