99 lines
4.6 KiB
Org Mode
99 lines
4.6 KiB
Org Mode
:PROPERTIES:
|
|
:ID: 36fe6a01-ea1f-4785-8516-f6dcfecf05bb
|
|
:END:
|
|
|
|
#+title: azos/architecture
|
|
#+filetags: :project: :knowledge: :architecture:
|
|
|
|
* Architecture
|
|
|
|
azos is a NixOS/home-manager configuration repo with a two-tier feature system:
|
|
|
|
- =azos-core/= — git submodule containing shared, reusable features (base, editor, claude-memory, claude-skills, dev, etc.)
|
|
- =features/= — machine-specific features (claude, encryption, hyprland, audio, etc.)
|
|
- =home-manager/home.nix= — home-manager entry point; manually lists all modules to import
|
|
- =_machines/= — per-machine NixOS configs; passes =suiteModules= as =specialArgs=
|
|
|
|
Feature auto-discovery is via =import-tree= in each flake.nix. Features from both
|
|
=azos-core/features/= and =azos/features/= are collected into =config.flake.modules=.
|
|
|
|
** Module registration pattern
|
|
|
|
Each feature's =default.nix= registers itself:
|
|
|
|
#+begin_src nix
|
|
config.flake.modules.homeManager.<name> = { lib, config, pkgs, ... }: {
|
|
options.azos.<name>.enable = lib.mkOption { ... };
|
|
config = lib.mkIf config.azos.<name>.enable { ... };
|
|
};
|
|
#+end_src
|
|
|
|
Modules are then imported in =home-manager/home.nix= via:
|
|
|
|
#+begin_src nix
|
|
imports = [ suiteModules.homeManager.<name> ... ];
|
|
#+end_src
|
|
|
|
** Option namespace
|
|
|
|
=azos.<feature-name>.<option-name>=
|
|
|
|
Dependencies between features use =lib.mkDefault true= to auto-enable:
|
|
|
|
#+begin_src nix
|
|
azos.claude-memory.enable = lib.mkDefault true;
|
|
azos.claude-skills.enable = lib.mkDefault true;
|
|
#+end_src
|
|
|
|
** File deployment
|
|
|
|
- Static files: =home.file."path".source = ./file;=
|
|
- Generated text: =home.file."path".text = "...";=
|
|
- Runtime scripts (e.g. merging JSON): =home.activation.<name> = lib.hm.dag.entryAfter ["writeBoundary"] ''...'';=
|
|
|
|
** Claude Code integration
|
|
|
|
Three azos-core features wire up Claude Code:
|
|
- =claude-memory= — registers org-roam-mcp as a global MCP server in =~/.claude.json=
|
|
- =claude-skills= — deploys skills to =~/.claude/commands/= and content to =~/.claude/CLAUDE.md=
|
|
- =claude= (=azos/features=) — installs claude-code, auto-enables the above two
|
|
|
|
** Packaging Emacs packages not in nixpkgs
|
|
|
|
=epkgs= (passed into =azos-core/features/editor/emacs/_pkg.nix=) is =pkgs.emacs.pkgs=, i.e.
|
|
nixpkgs' generated melpa package set — it lags real MELPA/GitHub by a while, so
|
|
brand-new packages (e.g. from an active author) are often missing.
|
|
|
|
Pattern used for =gptel=, =gptel-autocomplete=, =latex-to-svg-backend=,
|
|
=agent-shell-math-renderer=: define a =let= binding in =_pkg.nix= using
|
|
=epkgs.callPackage epkgs.trivialBuild { pname; version; src = pkgs.fetchFromGitHub {...}; buildInputs = [...]; }=,
|
|
then reference that binding in the =packageRequires= list. Get the =rev= via
|
|
=git ls-remote <url> HEAD=, and the =sha256= via
|
|
=nix-prefetch-url --unpack --type sha256 https://github.com/<owner>/<repo>/archive/<rev>.tar.gz=
|
|
then =nix hash convert --hash-algo sha256 --to sri <hash>= to get the SRI form used elsewhere in the repo.
|
|
Inter-package deps (e.g. agent-shell-math-renderer needs agent-shell + latex-to-svg-backend)
|
|
go in that package's =buildInputs=.
|
|
|
|
Sandbox note: during the trivialBuild native-compile step you'll see
|
|
"Failed to install <pkg>: Creating directory: Permission denied, /homeless-shelter" —
|
|
this is benign sandbox noise (no HOME during build), not a build failure; the derivation
|
|
still completes and installs correctly. Same warning already appears for gptel-autocomplete.
|
|
|
|
** LaTeX-to-SVG rendering (latex-to-svg-backend / agent-shell-math-renderer)
|
|
|
|
=latex-to-svg-backend= compiles equations with =\documentclass[varwidth,border=2pt]{standalone}=
|
|
plus =\usepackage{amsmath,amssymb,xcolor}=. The system texlive (=azos-core/features/editor/_pkg.nix=,
|
|
overlay =pkgs.azos-tex=, a =texliveSmall.withPackages= closure used for org-mode LaTeX export too)
|
|
did NOT originally include the =standalone= document class or its =varwidth= dependency — this
|
|
caused silent "LaTeX-to-SVG compile failed" warnings in agent-shell with no equation rendered.
|
|
Fixed by adding =standalone=, =varwidth=, =amsfonts= (provides =amssymb.sty=), =xcolor=, and
|
|
=mylatexformat= (optional but enables the package's precompiled-preamble speedup;
|
|
=latex-to-svg-backend-precompile= defaults to t and falls back gracefully if missing) to that
|
|
package list. Verified by hand: =latex= (from =pkgs.azos-tex=) then =dvisvgm= on a test equation
|
|
with the exact preamble above.
|
|
|
|
General gotcha: if a new agent-shell/org LaTeX-preview package starts throwing
|
|
"compile failed" / missing =.sty= errors, check =azos-core/features/editor/_pkg.nix= (=azos-tex=
|
|
overlay) for the missing texlive package name — the error log path is printed in the Emacs
|
|
warning (e.g. =~/.cache/emacs/latex-to-svg/svg/<hash>.log=) and gives the exact missing file.
|