backup: 2026-10-05 09:48

2026-10-05 09:48:25 +03:00
parent 2a872c725b
commit 32009710da
34 changed files with 1914 additions and 110 deletions
@@ -57,3 +57,42 @@ 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.