From 3000459155b68afb6dcd701d52ffab9d1345c949 Mon Sep 17 00:00:00 2001
From: Francesco Gazzetta <fgaz@fgaz.me>
Date: Mon, 7 Oct 2024 15:55:46 +0200
Subject: [PATCH] doc: Add Tcl doc

---
 ci/OWNERS                               |  1 +
 doc/languages-frameworks/index.md       |  1 +
 doc/languages-frameworks/tcl.section.md | 54 +++++++++++++++++++++++++
 3 files changed, 56 insertions(+)
 create mode 100644 doc/languages-frameworks/tcl.section.md

diff --git a/ci/OWNERS b/ci/OWNERS
index 1b38ca71df0f..e906b3281f30 100644
--- a/ci/OWNERS
+++ b/ci/OWNERS
@@ -182,6 +182,7 @@ nixos/modules/installer/tools/nix-fallback-paths.nix  @NixOS/nix-team @raitobeza
 /pkgs/development/libraries/tk      @fgaz
 /pkgs/top-level/tcl-packages.nix    @fgaz
 /pkgs/development/tcl-modules       @fgaz
+/doc/languages-frameworks/tcl.section.md @fgaz
 
 # C compilers
 /pkgs/development/compilers/gcc
diff --git a/doc/languages-frameworks/index.md b/doc/languages-frameworks/index.md
index c21f73e69a25..a8a13ce5b9e2 100644
--- a/doc/languages-frameworks/index.md
+++ b/doc/languages-frameworks/index.md
@@ -93,6 +93,7 @@ ruby.section.md
 rust.section.md
 scheme.section.md
 swift.section.md
+tcl.section.md
 texlive.section.md
 titanium.section.md
 vim.section.md
diff --git a/doc/languages-frameworks/tcl.section.md b/doc/languages-frameworks/tcl.section.md
new file mode 100644
index 000000000000..71ec9d89eb50
--- /dev/null
+++ b/doc/languages-frameworks/tcl.section.md
@@ -0,0 +1,54 @@
+# Tcl {#sec-language-tcl}
+
+## User guide {#sec-language-tcl-user-guide}
+
+Tcl interpreters are available under the `tcl` and `tcl-X_Y` attributes, where `X_Y` is the Tcl version.
+
+Tcl libraries are available in the `tclPackages` attribute set.
+They are only guaranteed to work with the default Tcl version, but will probably also work with others thanks to the [stubs mechanism](https://wiki.tcl-lang.org/page/Stubs).
+
+## Packaging guide {#sec-language-tcl-packaging}
+
+Tcl packages are typically built with `tclPackages.mkTclDerivation`.
+Tcl dependencies go in `buildInputs`/`nativeBuildInputs`/... like other packages.
+For more complex package definitions, such as packages with mixed languages, use `tcl.tclPackageHook`.
+
+Where possible, make sure to enable stubs for maximum compatibility, usually with the `--enable-stubs` configure flag.
+
+Here is a simple package example to be called with `tclPackages.callPackage`.
+
+```
+{ lib, fetchzip, mkTclDerivation, openssl }:
+
+mkTclDerivation rec {
+  pname = "tcltls";
+  version = "1.7.22";
+
+  src = fetchzip {
+    url = "https://core.tcl-lang.org/tcltls/uv/tcltls-${version}.tar.gz";
+    hash = "sha256-TOouWcQc3MNyJtaAGUGbaQoaCWVe6g3BPERct/V65vk=";
+  };
+
+  buildInputs = [ openssl ];
+
+  configureFlags = [
+    "--with-ssl-dir=${openssl.dev}"
+    "--enable-stubs"
+  ];
+
+  meta = {
+    homepage = "https://core.tcl-lang.org/tcltls/index";
+    description = "OpenSSL / RSA-bsafe Tcl extension";
+    maintainers = [ lib.maintainers.agbrooks ];
+    license = lib.licenses.tcltk;
+    platforms = lib.platforms.unix;
+  };
+}
+```
+
+All Tcl libraries are declared in `pkgs/top-level/tcl-packages.nix` and are defined in `pkgs/development/tcl-modules/`.
+If possible, prefer the by-name hierarchy in `pkgs/development/tcl-modules/by-name/`.
+Its use is documented in `pkgs/development/tcl-modules/by-name/README.md`.
+
+All Tcl applications reside elsewhere.
+In case a package is used as both a library and an application (for example `expect`), it should be defined in `tcl-packages.nix`, with an alias elsewhere.