From patchwork Sat Feb 1 11:43:23 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: 45mg <45mg.writes@gmail.com> X-Patchwork-Id: 38143 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 6D5DE27BBE2; Sat, 1 Feb 2025 11:46:44 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-6.6 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED,DKIM_VALID,FREEMAIL_FROM,MAILING_LIST_MULTI, RCVD_IN_DNSWL_BLOCKED,RCVD_IN_VALIDITY_CERTIFIED,RCVD_IN_VALIDITY_RPBL, RCVD_IN_VALIDITY_SAFE,SPF_HELO_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 060A727BBE9 for ; Sat, 1 Feb 2025 11:46:43 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1teBwv-0007Lq-Au; Sat, 01 Feb 2025 06:46:09 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1teBws-0007LE-PH for guix-patches@gnu.org; Sat, 01 Feb 2025 06:46:06 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1teBws-0005e6-Fr; Sat, 01 Feb 2025 06:46:06 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=F85/sIfvICd2GtgcoafUgDYLDpJBVD1bPSct/mRV/9k=; b=hN3LUc1+P7BqWvvIrvg2pnGPAyV/du1HnSuJMR1b7Un/qXxy29a/R3nBBg9UIj4h5/ZQGAoXN9Afirt2l8eci9pe4hFadYCHyZKs7ukJ/BoUNPs9Y2s073w+ExCRg5q+3jZfKWUnLdqGkOMfGnm8OcSlQ7iEiL2rtJeS7bxVG8wYLZv8XR+dW3pGNjikZ3pxATSrQcWXEReJuswP7t6BFim4vTvViMqskOha4tnScNXslhCHqE15JsKJsDSTGj3T7YWPhRuTo/4XkQjA0j5A7ARXiI12G6yq/aEqiLeyZz55u8PKsZ3vIuYtojwwKtz5zm8N9BDAtZXNbUA7aWTs+Q==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1teBwo-00056l-H7; Sat, 01 Feb 2025 06:46:02 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#75981] [PATCH (WIP) v1.5 1/4] Add 'guix fork create'. Resent-From: 45mg <45mg.writes@gmail.com> Original-Sender: "Debbugs-submit" Resent-CC: guix@cbaines.net, dev@jpoiret.xyz, ludo@gnu.org, othacehe@gnu.org, zimon.toutoune@gmail.com, me@tobias.gr, guix-patches@gnu.org Resent-Date: Sat, 01 Feb 2025 11:46:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 75981 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 75981@debbugs.gnu.org Cc: Nicolas Graves , Tomas Volf <~@wolfsden.cz>, 45mg <45mg.writes@gmail.com>, Liliana Marie Prikler , Ricardo Wurmus , Attila Lendvai , Christopher Baines , Josselin Poiret , Ludovic =?utf-8?q?Court=C3=A8s?= , Mathieu Othacehe , Simon Tournier , Tobias Geerinckx-Rice X-Debbugs-Original-Xcc: Christopher Baines , Josselin Poiret , Ludovic =?utf-8?q?Court=C3=A8s?= , Mathieu Othacehe , Simon Tournier , Tobias Geerinckx-Rice Received: via spool by 75981-submit@debbugs.gnu.org id=B75981.173841031819537 (code B ref 75981); Sat, 01 Feb 2025 11:46:02 +0000 Received: (at 75981) by debbugs.gnu.org; 1 Feb 2025 11:45:18 +0000 Received: from localhost ([127.0.0.1]:56710 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1teBw3-00052s-AA for submit@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:18 -0500 Received: from mail-pl1-x643.google.com ([2607:f8b0:4864:20::643]:52474) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from <45mg.writes@gmail.com>) id 1teBvz-0004yw-La for 75981@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:13 -0500 Received: by mail-pl1-x643.google.com with SMTP id d9443c01a7336-2165cb60719so52565045ad.0 for <75981@debbugs.gnu.org>; Sat, 01 Feb 2025 03:45:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1738410305; x=1739015105; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=F85/sIfvICd2GtgcoafUgDYLDpJBVD1bPSct/mRV/9k=; b=bK31Jf3XsQ3sIcYq0IOHUvA+9m5TvAeX2wWccNazc7IrwEClElwBKdEBqftKCDFBQr jaElJiurMPngHPCIlzvhl4MJrCB6MuW1S58izZFekgwA5RIJsfYmba+KHDsXOnTisqvW 2Rw2hiwnDfNKTjxn5BSpgIosrf7x1INYZEOi5EZKa8jXt8EnicbN8ABOwYwB/pBS8lh9 0JGS1DwVP2fxBBoUvi1krTIixZ8FUSHk1h4PJkU/6PM58uCXtwOi2I6MO8guhTTutcPi yb5jBJupoTPGbWSONWzeEhGV7GDJRE+tDjbF6TNM6N7N3xudpNtqKugNWfA5MTf4J4Kq ZlvQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738410305; x=1739015105; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=F85/sIfvICd2GtgcoafUgDYLDpJBVD1bPSct/mRV/9k=; b=ICkouMBKC59YswbarCLbxm1Xbrx7HBPxFCDBIbCkqSYakIL6FfuGJVFoV2/SsjzFeN j96h6LvNKvRsmTgYyhCxw9JzVrzcYvD6QOR1DrpI5jfAx3aF8u2GcXXMEM0fycby51DA exuY4G1512H5c2X4/doQofCkHuESl1Yw0maQQiSMlHYv2Jdmeec4Wz0X6TjAhQdJDsKm 1W3skJx8RIVI0jbt5OMA7QlzvWZEygWRcTHRQ7NTCPYXEKcZSxz5m+VCvqWYPj7vXSBl gwZlk0U8YOB1JmVKRd+Du8AWbYk+uHJRwPwFL3xF2eWywy3foBzk4luyTYqpSOMwa+1b P0zA== X-Gm-Message-State: AOJu0YxU9fL+wTTucMly11XhJgsvHG2da8Bd7dSW+nkRY63XudNAaBlA A8OrhVRc775CdYmW7UMfLtx+UhVDA0gn+NTGzi3A7ZyWgSoeze68/7aEk8rj X-Gm-Gg: ASbGnct43AWJarvH6DRJn84eySKEOstYlok61kAZ0TDedank90JkXmaRHKZqXa4Q6WJ xqSXPYX9rAl/YzVzFzRz9ltHc2RpTXglad2x9knFjb2NwmxDZOmIi6pNR45wE48x5oE3GBpqt8D tGZez7ANUd8WZzP/IzlMSFSnKpMzYSemsQHmh7FoMMDpGk22ReEM5273ONcPxMXlgbwcHFoCFtM prnna6F3T2AZ8+/3n7i/1W3JEbg46Hc7bsV0aowUZvLIRpjXElOZRlICRvySnEOgX6V0uLarCy8 sUMSAvWaFI0dYxs2YsN9lxm/9Y3fkeXJsiD+4A== X-Google-Smtp-Source: AGHT+IFgcnX80p98Lzc3vxehsQfdGymWiyMRQn2rF027BU+AZOJk/G87bILk+ezOCVYqIK/wf4ZgSA== X-Received: by 2002:a17:902:ec8a:b0:215:b473:1dc9 with SMTP id d9443c01a7336-21dd7de383fmr226484925ad.46.1738410304925; Sat, 01 Feb 2025 03:45:04 -0800 (PST) Received: from localhost.localdomain (utm3.nitt.edu. [14.139.162.2]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-21de331f8d4sm43844805ad.224.2025.02.01.03.45.01 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 01 Feb 2025 03:45:04 -0800 (PST) From: 45mg <45mg.writes@gmail.com> Date: Sat, 1 Feb 2025 17:13:23 +0530 Message-ID: <590b269995eb83d8fe2b584a40a58fa9ed473c54.1738408683.git.45mg.writes@gmail.com> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * guix/scripts/fork.scm, guix/scripts/fork/create.scm: New files. * Makefile.am (MODULES): Add the new files. * guix/build/utils.scm (invoke/stdout): New procedure. * guix/utils.scm (chain-cut): New procedure. * guix/scripts/git/authenticate.scm (commit-short-id): Remove procedure, and use its existing duplicate in guix/channels.scm. (openpgp-fingerprint*, current-branch, show-stats): Move procedures to the files below. * guix/channels.scm (openpgp-fingerprint*): Moved here. * guix/git.scm (repository-current-branch): Moved here and renamed from 'current-branch'. * guix/git-authenticate.scm (show-authentication-stats): Moved here and renamed from 'show-stats'. Change-Id: I45ba37f434e136f6d496c741d9a933280f9ccf88 --- Makefile.am | 2 + guix/channels.scm | 13 ++ guix/git-authenticate.scm | 17 ++ guix/git.scm | 10 ++ guix/scripts/fork.scm | 67 ++++++++ guix/scripts/fork/create.scm | 258 ++++++++++++++++++++++++++++++ guix/scripts/git/authenticate.scm | 45 +----- guix/utils.scm | 61 +++++++ 8 files changed, 432 insertions(+), 41 deletions(-) create mode 100644 guix/scripts/fork.scm create mode 100644 guix/scripts/fork/create.scm diff --git a/Makefile.am b/Makefile.am index f759803b8b..c628450a5a 100644 --- a/Makefile.am +++ b/Makefile.am @@ -377,6 +377,8 @@ MODULES = \ guix/scripts/size.scm \ guix/scripts/git.scm \ guix/scripts/git/authenticate.scm \ + guix/scripts/fork.scm \ + guix/scripts/fork/create.scm \ guix/scripts/graph.scm \ guix/scripts/weather.scm \ guix/scripts/container.scm \ diff --git a/guix/channels.scm b/guix/channels.scm index 4700f7a45d..6ca8e64881 100644 --- a/guix/channels.scm +++ b/guix/channels.scm @@ -47,6 +47,7 @@ (define-module (guix channels) #:use-module (guix packages) #:use-module (guix progress) #:use-module (guix derivations) + #:autoload (rnrs bytevectors) (bytevector-length) #:use-module (guix diagnostics) #:use-module (guix sets) #:use-module (guix store) @@ -81,6 +82,7 @@ (define-module (guix channels) openpgp-fingerprint->bytevector openpgp-fingerprint + openpgp-fingerprint* %default-guix-channel %default-channels @@ -171,6 +173,17 @@ (define-syntax openpgp-fingerprint ((_ str) #'(openpgp-fingerprint->bytevector str))))) +(define (openpgp-fingerprint* str) + "Like openpgp-fingerprint, but with error handling from (guix diagnostics)." + (unless (string-every (char-set-union char-set:hex-digit + char-set:whitespace) + str) + (leave (G_ "~a: invalid OpenPGP fingerprint~%") str)) + (let ((fingerprint (openpgp-fingerprint str))) + (unless (= 20 (bytevector-length fingerprint)) + (leave (G_ "~a: wrong length for OpenPGP fingerprint~%") str)) + fingerprint)) + (define %guix-channel-introduction ;; Introduction of the official 'guix channel. The chosen commit is the ;; first one that introduces '.guix-authorizations' on the 'staging' diff --git a/guix/git-authenticate.scm b/guix/git-authenticate.scm index 37c69d0880..8bc7fb6fb3 100644 --- a/guix/git-authenticate.scm +++ b/guix/git-authenticate.scm @@ -40,6 +40,7 @@ (define-module (guix git-authenticate) #:use-module (rnrs bytevectors) #:use-module (rnrs io ports) #:use-module (ice-9 match) + #:use-module (ice-9 format) #:autoload (ice-9 pretty-print) (pretty-print) #:export (read-authorizations commit-signing-key @@ -52,6 +53,7 @@ (define-module (guix git-authenticate) repository-cache-key authenticate-repository + show-authentication-stats git-authentication-error? git-authentication-error-commit @@ -449,3 +451,18 @@ (define* (authenticate-repository repository start signer (oid->string (commit-id end-commit))) stats)))) + +(define (show-authentication-stats stats) + "Display STATS, an alist containing commit signing stats as returned by +'authenticate-repository'." + (format #t (G_ "Signing statistics:~%")) + (for-each (match-lambda + ((signer . count) + (format #t " ~a ~10d~%" + (openpgp-format-fingerprint + (openpgp-public-key-fingerprint signer)) + count))) + (sort stats + (match-lambda* + (((_ . count1) (_ . count2)) + (> count1 count2)))))) diff --git a/guix/git.scm b/guix/git.scm index 6ac6e4e3a2..afeacb53aa 100644 --- a/guix/git.scm +++ b/guix/git.scm @@ -59,6 +59,7 @@ (define-module (guix git) with-git-error-handling false-if-git-not-found repository-info + repository-current-branch update-cached-checkout url+commit->name latest-repository-commit @@ -401,6 +402,15 @@ (define (repository-info directory) (lambda _ (values #f #f #f)))) +(define (repository-current-branch repository) + "Return the name of the checked out branch of REPOSITORY or #f if it could +not be determined." + (and (not (repository-head-detached? repository)) + (let* ((head (repository-head repository)) + (name (reference-name head))) + (and (string-prefix? "refs/heads/" name) + (string-drop name (string-length "refs/heads/")))))) + (define* (update-submodules repository #:key (log-port (current-error-port)) (fetch-options #f)) diff --git a/guix/scripts/fork.scm b/guix/scripts/fork.scm new file mode 100644 index 0000000000..2d97bcb93f --- /dev/null +++ b/guix/scripts/fork.scm @@ -0,0 +1,67 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2025 45mg <45mg.writes@gmail.com> +;;; +;;; This file is part of GNU Guix. +;;; +;;; GNU Guix is free software; you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 3 of the License, or (at +;;; your option) any later version. +;;; +;;; GNU Guix is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with GNU Guix. If not, see . + +(define-module (guix scripts fork) + #:use-module (ice-9 match) + #:use-module (guix ui) + #:use-module (guix scripts) + #:export (guix-fork)) + +(define (show-help) + (display (G_ "Usage: guix fork ACTION ARGS... +Create and manage authenticated forks of Guix.\n")) + (newline) + (display (G_ "The valid values for ACTION are:\n")) + (newline) + (display (G_ "\ + create set up a fork of Guix\n")) + (newline) + (display (G_ " + -h, --help display this help and exit")) + (display (G_ " + -V, --version display version information and exit")) + (newline) + (show-bug-report-information)) + +(define %sub-commands '("create")) + +(define (resolve-sub-command name) + (let ((module (resolve-interface + `(guix scripts fork ,(string->symbol name)))) + (proc (string->symbol (string-append "guix-fork-" name)))) + (module-ref module proc))) + +(define-command (guix-fork . args) + (category plumbing) + (synopsis "operate on Guix forks") + + (with-error-handling + (match args + (() + (format (current-error-port) + (G_ "guix fork: missing sub-command~%"))) + ((or ("-h") ("--help")) + (leave-on-EPIPE (show-help)) + (exit 0)) + ((or ("-V") ("--version")) + (show-version-and-exit "guix fork")) + ((sub-command args ...) + (if (member sub-command %sub-commands) + (apply (resolve-sub-command sub-command) args) + (format (current-error-port) + (G_ "guix fork: invalid sub-command~%"))))))) diff --git a/guix/scripts/fork/create.scm b/guix/scripts/fork/create.scm new file mode 100644 index 0000000000..a9de204f23 --- /dev/null +++ b/guix/scripts/fork/create.scm @@ -0,0 +1,258 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2025 Tomas Volf <~@wolfsden.cz> +;;; Copyright © 2025 45mg <45mg.writes@gmail.com> +;;; +;;; This file is part of GNU Guix. +;;; +;;; GNU Guix is free software; you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 3 of the License, or (at +;;; your option) any later version. +;;; +;;; GNU Guix is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with GNU Guix. If not, see . + +(define-module (guix scripts fork create) + #:use-module (guix ui) + #:use-module (guix scripts) + #:use-module ((guix utils) #:select (chain-cut + invoke/stdout)) ;TODO move to (guix build utils) + #:use-module (guix build utils) + #:use-module (guix channels) + #:use-module (ice-9 exceptions) + #:use-module (ice-9 match) + #:use-module (ice-9 popen) + #:use-module (ice-9 pretty-print) + #:use-module (ice-9 string-fun) + #:use-module (ice-9 textual-ports) + #:use-module (srfi srfi-1) + #:use-module (srfi srfi-13) + #:use-module (srfi srfi-26) + #:use-module (srfi srfi-37) + #:use-module (srfi srfi-71) + #:export (guix-fork-create)) + +;;; Commentary: +;;; +;;; Create a fork of Guix, by running a series of git commands. +;;; +;;; Code: + +(define %options + ;; Specifications of the command-line options. + (list (option '(#\h "help") #f #f + (lambda args + (show-help) + (exit 0))) + (option '(#\V "version") #f #f + (lambda args + (show-version-and-exit "guix fork create"))) + (option '("upstream") #t #f + (lambda (opt name arg result) + (alist-cons 'upstream arg result))) + (option '("channel-url") #t #f + (lambda (opt name arg result) + (alist-cons 'channel-url arg result))) + (option '("use-existing") #f #f + (lambda (opt name arg result) + (alist-cons 'use-existing? #t result))) + (option '("git-parameter") #t #f + (lambda (opt name arg result) + (let ((git-parameters (assoc-ref result 'git-parameters))) + (if git-parameters + (alist-cons 'git-parameters (cons arg git-parameters) result) + (alist-cons 'git-parameters (list arg) result))))))) + +(define %default-options + `((upstream . ,(channel-url %default-guix-channel)))) + +(define %usage + (format #f (G_ "Usage: guix fork create SIGNING_KEY [DIRECTORY OPTIONS...] +Create a fork of Guix in DIRECTORY, using SIGNING_KEY to sign the introductory +commit. +DIRECTORY defaults to ./guix. + + --upstream=URI the repository to clone from + (defaults to ~a) + --channel-url=URI optional URI, used to replace the channel URL + and the existing 'origin' remote (which is + renamed to 'upstream') + --use-existing Use existing clone of Guix in DIRECTORY + --git-parameter PARAMETER + Specify configuration PARAMETER for git, via + '-c' option (can pass multiple times) + + -h, --help display this help and exit + -V, --version display version information and exit +") + (channel-url %default-guix-channel))) + +(define (show-help) + (display %usage) + (newline) + (show-bug-report-information)) + +(define (missing-arguments) + (leave (G_ "wrong number of arguments; \ +required SIGNING_KEY~%"))) + + +;;; +;;; Helper prodecures. +;;; + +(define (fingerprint->key-file-name fingerprint) + (let* ((listing (invoke/stdout "gpg" "--list-key" "--with-colons" fingerprint)) + (uid (chain-cut listing + (string-split <> #\newline) + (filter (cut string-prefix? "uid:" <>) <>) + first + (string-split <> #\:) + tenth)) + (email-name (string-delete + (cut eq? <> #\.) + (substring uid + (1+ (or (string-index-right uid #\<) + -1)) ;no name in uid + (string-index uid #\@)))) + (key-id (chain-cut listing + (string-split <> #\newline) + (filter (cut string-prefix? "pub:" <>) <>) + car + (string-split <> #\:) + fifth + (string-take-right <> 8)))) + (string-append email-name "-" key-id ".key"))) + +(define (update-channel-url file channel-url) + "Modify .guix_channel FILE. +Change the channel url to CHANNEL-URL." + (let ((channel-data (call-with-input-file file read))) + (assq-set! (cdr channel-data) 'url (list channel-url)) + (call-with-output-file file + (lambda (file) + (display ";; This is a Guix channel.\n\n" file) + (pretty-print channel-data file))))) + +(define (rewrite-authorizations file name fingerprint) + "Rewrite .guix-authorizations FILE to contain a single authorization +consisting of NAME and FINGERPRINT." + (let ((auth-data (call-with-input-file file read))) + (list-set! auth-data (1- (length auth-data)) + `((,fingerprint (name ,name)))) + (call-with-output-file file + (lambda (file) + (display ";; This file, which is best viewed as -*- Scheme -*-, lists the OpenPGP keys +;; currently authorized to sign commits in this fork branch. + +" file) + (pretty-print auth-data file))))) + + +;;; +;;; Entry point. +;;; + +(define (guix-fork-create . args) + (define options + (parse-command-line args %options (list %default-options) + #:build-options? #f)) + + (define (command-line-arguments lst) + (reverse (filter-map (match-lambda + (('argument . arg) arg) + (_ #f)) + lst))) + + (with-error-handling + (let* ((signing-key directory (match (command-line-arguments options) + ((signing-key directory) + (values signing-key directory)) + ((signing-key) + (values signing-key "guix")) + (_ (missing-arguments)))) + (upstream (assoc-ref options 'upstream)) + (channel-url (assoc-ref options 'channel-url)) + (use-existing? (assoc-ref options 'use-existing?)) + (git-parameters (assoc-ref options 'git-parameters)) + (git-c-options ;'("-c" "param1" "-c" "param2" ...) + (let loop ((opts '()) (params git-parameters)) + (if (or (not params) (null-list? params)) + opts + (loop (append + opts (list "-c" (first params))) + (drop params 1))))) + + (key-file-name (fingerprint->key-file-name signing-key)) + (introduction-name (car (string-split key-file-name #\-))) + + (upstream-branch-name "master")) + + (define (invoke-git . args) + (apply invoke `("git" ,@git-c-options "-C" ,directory ,@args))) + + (unless use-existing? + (info (G_ "Cloning from upstream ~a...~%") upstream) + (invoke "git" "clone" upstream directory)) + + (info (G_ "Authenticating upstream commits...~%")) + + (when channel-url + (info (G_ "Renaming existing 'origin' remote to 'upstream'...~%")) + (invoke-git "remote" "rename" "origin" "upstream") + (info (G_ "Using provided channel URL for new 'origin' remote...~%")) + (invoke-git "remote" "add" "origin" channel-url)) + + (set! upstream-branch-name + (chain-cut + (invoke/stdout "git" + "-C" directory + "symbolic-ref" + (string-append "refs/remotes/" + (if channel-url "upstream" "origin") + "/HEAD")) + string-trim-right + (string-split <> #\/) + last)) + + (info (G_ "Adding key to keyring branch...~%")) + (invoke-git "switch" "keyring") + (invoke "gpg" + "--armor" "--export" + "-o" (string-append directory "/" key-file-name) + signing-key) + (invoke-git "add" "--" key-file-name) + (invoke-git "commit" "-m" "Add key for fork introduction.") + + (info (G_ "Setting up fork branch...~%")) + (invoke-git "switch" "--create" "fork" "master") + (when channel-url + (update-channel-url (string-append directory "/.guix-channel") + channel-url)) + (rewrite-authorizations (string-append directory "/.guix-authorizations") + introduction-name signing-key) + (invoke-git "add" "--" + (string-append directory "/.guix-authorizations") + (string-append directory "/.guix-channel")) + (invoke-git "commit" + (string-append "--gpg-sign=" signing-key) + "-m" + (string-append + "Initial fork commit.\n\n" + ".guix-authorizations: Allow only " introduction-name "'s key." + (if channel-url + "\n.guix-channels: Update channel URL." + ""))) + + (info (G_ "Successfully created Guix fork in ~a. +You should run the following command next: +guix fork authenticate ~a ~a ~a~%") + directory + upstream-branch-name + (string-trim-right (invoke/stdout "git" "-C" directory "rev-parse" "HEAD")) + signing-key)))) diff --git a/guix/scripts/git/authenticate.scm b/guix/scripts/git/authenticate.scm index e3ecb67c89..154aae9b14 100644 --- a/guix/scripts/git/authenticate.scm +++ b/guix/scripts/git/authenticate.scm @@ -23,8 +23,8 @@ (define-module (guix scripts git authenticate) #:use-module (guix git-authenticate) #:autoload (guix openpgp) (openpgp-format-fingerprint openpgp-public-key-fingerprint) - #:use-module ((guix channels) #:select (openpgp-fingerprint)) - #:use-module ((guix git) #:select (with-git-error-handling)) + #:use-module ((guix channels) #:select (openpgp-fingerprint*)) + #:use-module ((guix git) #:select (with-git-error-handling commit-short-id repository-current-branch)) #:use-module (guix progress) #:use-module (guix base64) #:autoload (rnrs bytevectors) (bytevector-length) @@ -76,15 +76,6 @@ (define %options (define %default-options '()) -(define (current-branch repository) - "Return the name of the checked out branch of REPOSITORY or #f if it could -not be determined." - (and (not (repository-head-detached? repository)) - (let* ((head (repository-head repository)) - (name (reference-name head))) - (and (string-prefix? "refs/heads/" name) - (string-drop name (string-length "refs/heads/")))))) - (define (config-value repository key) "Return the config value associated with KEY in the 'guix.authentication' or 'guix.authentication-BRANCH' name space in REPOSITORY, or #f if no such config @@ -94,7 +85,7 @@ (define (config-value repository key) ((_ exp) (catch 'git-error (lambda () exp) (const #f)))))) (let* ((config (repository-config repository)) - (branch (current-branch repository))) + (branch (repository-current-branch repository))) ;; First try the BRANCH-specific value, then the generic one.` (or (and branch (false-if-git-error @@ -194,21 +185,6 @@ (define (install-hooks repository) (warning (G_ "cannot determine where to install hooks\ (Guile-Git too old?)~%")))) -(define (show-stats stats) - "Display STATS, an alist containing commit signing stats as returned by -'authenticate-repository'." - (format #t (G_ "Signing statistics:~%")) - (for-each (match-lambda - ((signer . count) - (format #t " ~a ~10d~%" - (openpgp-format-fingerprint - (openpgp-public-key-fingerprint signer)) - count))) - (sort stats - (match-lambda* - (((_ . count1) (_ . count2)) - (> count1 count2)))))) - (define (show-help) (display (G_ "Usage: guix git authenticate COMMIT SIGNER [OPTIONS...] Authenticate the given Git checkout using COMMIT/SIGNER as its introduction.\n")) @@ -251,19 +227,6 @@ (define (guix-git-authenticate . args) (_ #f)) lst))) - (define commit-short-id - (compose (cut string-take <> 7) oid->string commit-id)) - - (define (openpgp-fingerprint* str) - (unless (string-every (char-set-union char-set:hex-digit - char-set:whitespace) - str) - (leave (G_ "~a: invalid OpenPGP fingerprint~%") str)) - (let ((fingerprint (openpgp-fingerprint str))) - (unless (= 20 (bytevector-length fingerprint)) - (leave (G_ "~a: wrong length for OpenPGP fingerprint~%") str)) - fingerprint)) - (define (make-reporter start-commit end-commit commits) (format (current-error-port) (G_ "Authenticating commits ~a to ~a (~h new \ @@ -321,7 +284,7 @@ (define (guix-git-authenticate . args) (install-hooks repository)) (when (and show-stats? (not (null? stats))) - (show-stats stats)) + (show-authentication-stats stats)) (info (G_ "successfully authenticated commit ~a~%") (oid->string end)))))) diff --git a/guix/utils.scm b/guix/utils.scm index b6cf5aea4f..0d023e7729 100644 --- a/guix/utils.scm +++ b/guix/utils.scm @@ -21,6 +21,8 @@ ;;; Copyright © 2023 Zheng Junjie <873216071@qq.com> ;;; Copyright © 2023 Foundation Devices, Inc. ;;; Copyright © 2024 Herman Rimm +;;; Copyright © 2025 Tomas Volf <~@wolfsden.cz> +;;; Copyright © 2025 45mg <45mg.writes@gmail.com> ;;; ;;; This file is part of GNU Guix. ;;; @@ -44,6 +46,8 @@ (define-module (guix utils) #:use-module (srfi srfi-11) #:use-module (srfi srfi-26) #:use-module (srfi srfi-71) + #:use-module (srfi srfi-35) ;TODO remove after moving invoke/stdout + #:use-module (ice-9 popen) ;TODO remove after moving invoke/stdout #:use-module (rnrs io ports) ;need 'port-position' etc. #:use-module ((rnrs bytevectors) #:select (bytevector-u8-set!)) #:use-module (guix memoization) @@ -163,6 +167,9 @@ (define-module (guix utils) call-with-compressed-output-port canonical-newline-port + chain-cut + invoke/stdout ;TODO move to (guix build utils) + string-distance string-closest @@ -1193,6 +1200,60 @@ (define-syntax current-source-directory ;; raising an error would upset Geiser users #f)))))) + +;;; +;;; Higher-order functions. +;;; + +(define-syntax chain-cut + (lambda (x) + "Apply each successive form to the result of evaluating the previous one. +Before applying, expand each form (op ...) to (cut op ...). + +Examples: + + (chain-cut '(1 2 3) cdr car) + => (car (cdr '(1 2 3))) + + (chain-cut 2 (- 3 <>) 1+) + => (1+ ((cut - 3 <>) 2)) + => (1+ (- 3 2)) +" + (syntax-case x () + ((chain-cut init op) (identifier? #'op) + #'(op init)) + ((chain-cut init (op ...)) + #'((cut op ...) init)) + ((chain-cut init op op* ...) (identifier? #'op) + #'(chain-cut (op init) op* ...)) + ((chain-cut init (op ...) op* ...) + #'(chain-cut ((cut op ...) init) op* ...))))) + +;; Copied from (guix build utils); remove +(define-condition-type &invoke-error &error + invoke-error? + (program invoke-error-program) + (arguments invoke-error-arguments) + (exit-status invoke-error-exit-status) + (term-signal invoke-error-term-signal) + (stop-signal invoke-error-stop-signal)) +;; TODO move to (guix build utils) +(define (invoke/stdout program . args) + "Invoke PROGRAM with ARGS and capture PROGRAM's standard output. If PROGRAM +succeeds, return its standard output as a string. Otherwise, raise an +'&invoke-error' condition." + (let* ((port (apply open-pipe* OPEN_READ program args)) + (data (get-string-all port)) + (code (close-pipe port))) + (unless (zero? code) + (raise (condition (&invoke-error + (program program) + (arguments args) + (exit-status (status:exit-val code)) + (term-signal (status:term-sig code)) + (stop-signal (status:stop-sig code)))))) + data)) + ;;; ;;; String comparison. From patchwork Sat Feb 1 11:43:24 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: 45mg <45mg.writes@gmail.com> X-Patchwork-Id: 38141 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 36B3B27BBE9; Sat, 1 Feb 2025 11:46:39 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-6.6 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED,DKIM_VALID,FREEMAIL_FROM,MAILING_LIST_MULTI, RCVD_IN_DNSWL_BLOCKED,RCVD_IN_VALIDITY_CERTIFIED,RCVD_IN_VALIDITY_RPBL, RCVD_IN_VALIDITY_SAFE,SPF_HELO_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id CD00F27BBE2 for ; Sat, 1 Feb 2025 11:46:36 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1teBwv-0007M1-S6; Sat, 01 Feb 2025 06:46:09 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1teBwt-0007Lc-Pp for guix-patches@gnu.org; Sat, 01 Feb 2025 06:46:07 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1teBwt-0005eH-G6; Sat, 01 Feb 2025 06:46:07 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=rASlCkCXzp5SO8O1bmNfoaP77uE1mhNlivO/wDiYLuQ=; b=BEIM1ecWOPFT+8MWeXeR1SSLumWRH7WewjPSsby+VOmu4j9qBSCx/k8KjXi2nH9WWTImcDYClkLK9CFQq53hCooPMLUT7N6UaokiVAFKY/1QD6udDZdbjem7BU6XaVqGpNXK2zpwezmzk4uy+gsAaUaiyw2dyDx+R5egO3brKM1lty4BKHvYn/7SBerE+pk6lP06aF6TX751VFZeRPTiX8rgZJ63HI4KClLi0iZG7wUGHPzjtrt1LO5Tt92/ZLOO+0KrSBGG17kXiV6I8ys3U2x/wlnWc+praj/7nGZz5MXH0KZcLhuze3D/ZUOj8WtLK4i4qdxukJv0oXYRyq2jVQ==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1teBwp-00056u-0A; Sat, 01 Feb 2025 06:46:03 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#75981] [PATCH (WIP) v1.5 2/4] Add 'guix fork authenticate'. Resent-From: 45mg <45mg.writes@gmail.com> Original-Sender: "Debbugs-submit" Resent-CC: guix@cbaines.net, dev@jpoiret.xyz, ludo@gnu.org, othacehe@gnu.org, zimon.toutoune@gmail.com, me@tobias.gr, guix-patches@gnu.org Resent-Date: Sat, 01 Feb 2025 11:46:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 75981 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 75981@debbugs.gnu.org Cc: Nicolas Graves , Tomas Volf <~@wolfsden.cz>, 45mg <45mg.writes@gmail.com>, Liliana Marie Prikler , Ricardo Wurmus , Attila Lendvai , Christopher Baines , Josselin Poiret , Ludovic =?utf-8?q?Court=C3=A8s?= , Mathieu Othacehe , Simon Tournier , Tobias Geerinckx-Rice X-Debbugs-Original-Xcc: Christopher Baines , Josselin Poiret , Ludovic =?utf-8?q?Court=C3=A8s?= , Mathieu Othacehe , Simon Tournier , Tobias Geerinckx-Rice Received: via spool by 75981-submit@debbugs.gnu.org id=B75981.173841032119556 (code B ref 75981); Sat, 01 Feb 2025 11:46:02 +0000 Received: (at 75981) by debbugs.gnu.org; 1 Feb 2025 11:45:21 +0000 Received: from localhost ([127.0.0.1]:56715 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1teBw8-00055J-R4 for submit@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:21 -0500 Received: from mail-pl1-x643.google.com ([2607:f8b0:4864:20::643]:44152) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from <45mg.writes@gmail.com>) id 1teBw5-0004zT-Lk for 75981@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:18 -0500 Received: by mail-pl1-x643.google.com with SMTP id d9443c01a7336-2163dc5155fso51735555ad.0 for <75981@debbugs.gnu.org>; Sat, 01 Feb 2025 03:45:17 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1738410311; x=1739015111; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=rASlCkCXzp5SO8O1bmNfoaP77uE1mhNlivO/wDiYLuQ=; b=OpXS9t5uqGAXcd6qM4ibbJPp+WQEumoRnshZJFV6ueOI6UIC+OVId9LhhheSd4ZNwm yLhVXLZEWA77lQutke0LcGHdWmVppbR2CE2F65kGXlYA+2fVhvknAKJsaH6cOXZN+5d/ KICk7JX3+u4J4bPnVBJ5eZBSwE2e+hj7eywtFA1TCSTrYIQGYpaUJg0FrchL/OO2Ew3k wONBRRjI2AsSLqGAn1Lce3//F7uIzpDpdl8ZP5mzZHbV6GBBeyjxsb35ePqP7ld9b9yO bJCiYhJg/BSMOfUqgYZ5zsM+gD4n9IhJhH1GPswg4HEmjULXOGYsCITqcwfeYzcBQX1V a+FQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738410311; x=1739015111; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=rASlCkCXzp5SO8O1bmNfoaP77uE1mhNlivO/wDiYLuQ=; b=gYqUr8oQAosa4tgYOVcU8TK2NM/JRMGdmDIV5/VdCAr1756pBilSeE0qEui+JBSRuL U6tKw3qnfgWMcygLqklKWmf3+fGHF5wZG6UbI0zd5JmxbTI/beZxdZ3UHHKi39kmkGRU hRia9sS1kMoK1fgnC6nqvkznK0pQor1BbepXSIXhzGnpciOGdAPrd1ygYcKGGZQqWjM7 gkMthX5eFIU60BK6zQKPC17spKi/pYSFnz/7NYxGoD18oemKCHgf78ZyAaNHFZECptek Ihc+ukUEA2n1hLluebeRFr0wxbq7j8UG2aDi4pYA6k51cHTxaVoQP5Pgd3qHaMCva/YO i87A== X-Gm-Message-State: AOJu0YyQHEYm/6imDF7nL81D47z/JXDr75ZZzPzfinS9Hx4FfR2cgD5D axqGc/OLpIW9terq2xFto5ameEhj5f786MgJinKlo6k4Qwf8jozDGRGxf8C0 X-Gm-Gg: ASbGnctXNolmGTd7BiUvBdvXWDrjn9jQVExAWiB6Gkp3Y6dGRNIRs0Jzw4QuoVFHCwP ZixIHpxksmJN/jhyQtUvJbxeHrnihByyVmOiXu0WAPNzdDz1WNsZqbFM9hKe7Kszr1mvGCzGvGj pq1Ho7tYgCPk9w+Pr3Xdx/ps/7OZ67GpbDVNBsOH8DrdvnGH150yJPEmJn8reCMVTJLiGU3ZM6q otYoQTmexJ+17ra6BCZ7/rZ2oUXYthkWXhEYD2j2xuStG0M0f7W90cRSI+rvm4E0GRadddRKJiZ zaIEbE02gqCSD5Oa7dCDcsQUeugLz5TZugLVJw== X-Google-Smtp-Source: AGHT+IFcnPO2E7PW+B4+upoT1IISmq3tOZpDVa1M8GbwVvH5e2u8cOriHdnRF/I+IKYfDIiFfadHgA== X-Received: by 2002:a17:902:c40a:b0:212:63c0:d9e7 with SMTP id d9443c01a7336-21dd7b61a82mr236607115ad.0.1738410311115; Sat, 01 Feb 2025 03:45:11 -0800 (PST) Received: from localhost.localdomain (utm3.nitt.edu. [14.139.162.2]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-21de331f8d4sm43844805ad.224.2025.02.01.03.45.08 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 01 Feb 2025 03:45:10 -0800 (PST) From: 45mg <45mg.writes@gmail.com> Date: Sat, 1 Feb 2025 17:13:24 +0530 Message-ID: <10c11dfc090e48aa6a3f4b1fd67543ec2bab7b40.1738408683.git.45mg.writes@gmail.com> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * guix/scripts/fork/authenticate.scm: New file. * Makefile.am (MODULES): Add the new file. * guix/scripts/fork.scm (show-help): Mention new command. (%sub-commands): Add new command. Change-Id: Ic34a1b3d1642cedce8d1ff5bae825df30e47755c --- Makefile.am | 1 + guix/scripts/fork.scm | 6 +- guix/scripts/fork/authenticate.scm | 331 +++++++++++++++++++++++++++++ 3 files changed, 336 insertions(+), 2 deletions(-) create mode 100644 guix/scripts/fork/authenticate.scm diff --git a/Makefile.am b/Makefile.am index c628450a5a..1c1f5d84fd 100644 --- a/Makefile.am +++ b/Makefile.am @@ -379,6 +379,7 @@ MODULES = \ guix/scripts/git/authenticate.scm \ guix/scripts/fork.scm \ guix/scripts/fork/create.scm \ + guix/scripts/fork/authenticate.scm \ guix/scripts/graph.scm \ guix/scripts/weather.scm \ guix/scripts/container.scm \ diff --git a/guix/scripts/fork.scm b/guix/scripts/fork.scm index 2d97bcb93f..c5c7a59ba7 100644 --- a/guix/scripts/fork.scm +++ b/guix/scripts/fork.scm @@ -29,7 +29,9 @@ (define (show-help) (display (G_ "The valid values for ACTION are:\n")) (newline) (display (G_ "\ - create set up a fork of Guix\n")) + create set up a fork of Guix\n")) + (display (G_ "\ + authenticate authenticate a fork of Guix\n")) (newline) (display (G_ " -h, --help display this help and exit")) @@ -38,7 +40,7 @@ (define (show-help) (newline) (show-bug-report-information)) -(define %sub-commands '("create")) +(define %sub-commands '("create" "authenticate")) (define (resolve-sub-command name) (let ((module (resolve-interface diff --git a/guix/scripts/fork/authenticate.scm b/guix/scripts/fork/authenticate.scm new file mode 100644 index 0000000000..83d9d87d44 --- /dev/null +++ b/guix/scripts/fork/authenticate.scm @@ -0,0 +1,331 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2025 45mg <45mg.writes@gmail.com> +;;; +;;; This file is part of GNU Guix. +;;; +;;; GNU Guix is free software; you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 3 of the License, or (at +;;; your option) any later version. +;;; +;;; GNU Guix is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with GNU Guix. If not, see . + +(define-module (guix scripts fork authenticate) + #:use-module (git) + #:use-module (guix git) + #:use-module (guix git-authenticate) + #:use-module (guix base16) + #:use-module (guix ui) + #:use-module (guix progress) + #:use-module (guix scripts) + #:use-module (guix build utils) + #:use-module (guix channels) + #:use-module (ice-9 exceptions) + #:use-module (ice-9 match) + #:use-module (ice-9 receive) + #:use-module (ice-9 popen) + #:use-module (ice-9 format) + #:use-module (ice-9 pretty-print) + #:use-module (ice-9 string-fun) + #:use-module (ice-9 textual-ports) + #:use-module (srfi srfi-1) + #:use-module (srfi srfi-13) + #:use-module (srfi srfi-26) + #:use-module (srfi srfi-37) + #:use-module (srfi srfi-71) + #:export (guix-fork-authenticate + + fork-config-value + fork-configured? + fork-configured-keyring-reference + fork-configured-introduction)) + +;;; Commentary: +;;; +;;; Authenticate a fork of Guix, in the same manner as `guix git +;;; authenticate`. +;;; +;;; Code: + +(define %options + ;; Specifications of the command-line options. + (list (option '(#\h "help") #f #f + (lambda args + (show-help) + (exit 0))) + (option '(#\V "version") #f #f + (lambda args + (show-version-and-exit "guix fork authenticate"))) + + (option '(#\r "repository") #t #f + (lambda (opt name arg result) + (alist-cons 'directory arg result))) + (option '("upstream-commit") #f #f + (lambda (opt name arg result) + (alist-cons 'upstream-commit (string->oid arg) result))) + (option '("upstream-signer") #f #f + (lambda (opt name arg result) + (alist-cons 'upstream-signer (openpgp-fingerprint* arg) result))) + + (option '(#\e "end") #t #f + (lambda (opt name arg result) + (alist-cons 'end-commit (string->oid arg) result))) + (option '("upstream-end") #t #f + (lambda (opt name arg result) + (alist-cons 'upstream-end-commit (string->oid arg) result))) + (option '(#\k "keyring") #t #f + (lambda (opt name arg result) + (alist-cons 'keyring-reference arg result))) + (option '("upstream-keyring") #t #f + (lambda (opt name arg result) + (alist-cons 'upstream-keyring arg result))) + (option '("cache-key") #t #f + (lambda (opt name arg result) + (alist-cons 'cache-key arg result))) + (option '("historical-authorizations") #t #f + (lambda (opt name arg result) + (alist-cons 'historical-authorizations arg + result))) + (option '("stats") #f #f + (lambda (opt name arg result) + (alist-cons 'show-stats? #t result))))) + +(define %default-options + (let ((introduction (channel-introduction %default-guix-channel))) + `((upstream-commit + . ,(string->oid (channel-introduction-first-signed-commit introduction))) + (upstream-signer + . ,(openpgp-fingerprint + (string-upcase + (bytevector->base16-string + (channel-introduction-first-commit-signer introduction))))) + (upstream-keyring + . "keyring")))) + +(define %usage + (format #f (G_ "Usage: guix fork authenticate UPSTREAM COMMIT SIGNER [OPTIONS...] +Authenticate a fork of Guix, using COMMIT/SIGNER as the fork introduction. + +First, authenticate new commits from UPSTREAM, using Guix's default +introduction. Then authenticate the remaining commits using the fork +introduction. + + -r, --repository=DIRECTORY + Authenticate the Git repository in DIRECTORY + + --upstream-commit=COMMIT + --upstream-signer=SIGNER + Use COMMIT/SIGNER as the introduction for upstream + Guix, overriding the default values + ~a + /~a + (Guix's default introduction). + + -k, --keyring=REFERENCE + load keyring for fork commits from REFERENCE, a Git + branch (default \"keyring\") + --upstream-keyring=REFERENCE + load keyring for upstream commits from REFERENCE, a + Git branch (default \"keyring\") + --end=COMMIT authenticate fork commits up to COMMIT + --cache-key=KEY cache authenticated commits under KEY + --historical-authorizations=FILE + read historical authorizations from FILE + --stats Display commit signing statistics upon completion + + -h, --help display this help and exit + -V, --version display version information and exit +") + (assoc-ref %default-options 'upstream-commit) + (assoc-ref %default-options 'upstream-signer))) + +(define (show-help) + (display %usage) + (newline) + (show-bug-report-information)) + +(define (missing-arguments) + (leave (G_ "wrong number of arguments; \ +required UPSTREAM, COMMIT and SIGNER~%"))) + + +;;; +;;; Helper prodecures. +;;; + +(define (fork-config-value repository key) + "Return the config value associated with KEY in the +'guix.fork-authentication' namespace in REPOSITORY, or #f if no such config +was found." + (let* ((config (repository-config repository)) + (branch (repository-current-branch repository))) + (catch 'git-error + (lambda () + (config-entry-value + (config-get-entry config + (string-append "guix.fork-authentication." + key)))) + (const #f)))) + +(define (fork-configured-introduction repository) + "Return three values: the upstream branch name, introductory commit, and +signer fingerprint (strings) for this fork, as configured in REPOSITORY. +Error out if any were missing." + (let* ((upstream-branch (fork-config-value repository "upstream-branch")) + (commit (fork-config-value repository "introduction-commit")) + (signer (fork-config-value repository "introduction-signer"))) + (unless (and upstream-branch commit signer) + (leave (G_ "fork information in .git/config is incomplete; +missing at least one of +introduction-commit, introduction-signer, upstream-branch +under [guix \"fork-authentication\"]"))) + (values upstream-branch commit signer))) + +(define (fork-configured-keyring-reference repository) + "Return the keyring reference configured in REPOSITORY or #f if missing." + (fork-config-value repository "keyring")) + +(define (fork-configured? repository) + "Return true if REPOSITORY already contains fork introduction info in its +'config' file." + (and (fork-config-value repository "upstream-branch") + (fork-config-value repository "introduction-commit") + (fork-config-value repository "introduction-signer"))) + +(define* (record-fork-configuration + repository + #:key commit signer upstream-branch keyring-reference) + "Record COMMIT, SIGNER, UPSTREAM-BRANCH and KEYRING-REFERENCE in the +'config' file of REPOSITORY." + (define config + (repository-config repository)) + + ;; Guile-Git < 0.7.0 lacks 'set-config-string'. + (if (module-defined? (resolve-interface '(git)) 'set-config-string) + (begin + (set-config-string config "guix.fork-authentication.introduction-commit" + commit) + (set-config-string config "guix.fork-authentication.introduction-signer" + signer) + (set-config-string config "guix.fork-authentication.upstream-branch" + upstream-branch) + (set-config-string config "guix.fork-authentication.keyring" + keyring-reference) + (info (G_ "introduction, upstream branch and keyring recorded \ +in repository configuration file~%"))) + (warning (G_ "could not record introduction and keyring configuration\ + (Guile-Git too old?)~%")))) + + +(define (guix-fork-authenticate . args) + (define options + (parse-command-line args %options (list %default-options) + #:build-options? #f)) + + (define (command-line-arguments lst) + (reverse (filter-map (match-lambda + (('argument . arg) arg) + (_ #f)) + lst))) + + (define (make-reporter start-commit end-commit commits) + (format (current-error-port) + (G_ "Authenticating commits ~a to ~a (~h new \ +commits)...~%") + (commit-short-id start-commit) + (commit-short-id end-commit) + (length commits)) + (if (isatty? (current-error-port)) + (progress-reporter/bar (length commits)) + progress-reporter/silent)) + + (with-error-handling + (with-git-error-handling + ;; TODO: BUG: it doesn't recognize '~' in paths + ;; How to do 'realpath' in Guile? + (let* ((repository (repository-open (or (assoc-ref options 'directory) + (repository-discover ".")))) + (upstream commit signer (match (command-line-arguments options) + ((upstream commit signer) + (values + (branch-lookup repository upstream) + (string->oid commit) + (openpgp-fingerprint* signer))) + (() + (receive (upstream commit signer) + (fork-configured-introduction repository) + (values + (branch-lookup repository upstream) + (string->oid commit) + (openpgp-fingerprint* signer)))) + (_ + (missing-arguments)))) + (upstream-commit (assoc-ref options 'upstream-commit)) + (upstream-signer (assoc-ref options 'upstream-signer)) + (history (match (assoc-ref options 'historical-authorizations) + (#f '()) + (file (call-with-input-file file + read-authorizations)))) + (keyring (or (assoc-ref options 'keyring-reference) + (fork-configured-keyring-reference repository) + "keyring")) + (upstream-keyring (assoc-ref options 'upstream-keyring)) + (end (match (assoc-ref options 'end-commit) + (#f (reference-target + (repository-head repository))) + (oid oid))) + (upstream-end (match (assoc-ref options 'upstream-end-commit) + (#f + (reference-target upstream)) + (oid oid))) + (cache-key (or (assoc-ref options 'cache-key) + (repository-cache-key repository))) + (show-stats? (assoc-ref options 'show-stats?))) + + (define upstream-authentication-args + (filter identity + (list + (oid->string upstream-commit) + (bytevector->base16-string upstream-signer) + (string-append "--repository=" + (repository-directory repository)) + (string-append "--end=" + (oid->string upstream-end)) + (and upstream-keyring + (string-append "--keyring=" + upstream-keyring)) + (and show-stats? "--stats")))) + + (info (G_ "calling `guix git authenticate` for branch ~a...~%") + (branch-name upstream)) + + (apply run-guix-command 'git "authenticate" + upstream-authentication-args) + + (define fork-stats + (authenticate-repository + repository commit signer + #:end end + #:keyring-reference keyring + #:historical-authorizations history + #:cache-key cache-key + #:make-reporter make-reporter)) + + (unless (fork-configured? repository) + (record-fork-configuration repository + #:commit (oid->string commit) + #:signer (bytevector->base16-string signer) + #:upstream-branch (branch-name upstream) + #:keyring-reference keyring)) + + (when (and show-stats? (not (null? fork-stats))) + (show-authentication-stats fork-stats)) + + (info (G_ "successfully authenticated commit ~a~%") + (oid->string end)))))) From patchwork Sat Feb 1 11:43:25 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: 45mg <45mg.writes@gmail.com> X-Patchwork-Id: 38142 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 23E9727BBEA; Sat, 1 Feb 2025 11:46:42 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-6.6 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED,DKIM_VALID,FREEMAIL_FROM,MAILING_LIST_MULTI, RCVD_IN_DNSWL_BLOCKED,RCVD_IN_VALIDITY_CERTIFIED,RCVD_IN_VALIDITY_RPBL, RCVD_IN_VALIDITY_SAFE,SPF_HELO_PASS,URIBL_BLOCKED autolearn=unavailable autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 6BEB327BBE2 for ; Sat, 1 Feb 2025 11:46:41 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1teBws-0007Kz-8F; Sat, 01 Feb 2025 06:46:06 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1teBwq-0007Kg-NI for guix-patches@gnu.org; Sat, 01 Feb 2025 06:46:04 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1teBwq-0005dr-C2; Sat, 01 Feb 2025 06:46:04 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=C43SsUA5OCcbVBTaSANAj1vwibNoo1rJF1BpXIfZWW8=; b=m+xtx3RX34fCKSucQ8OCNTqH+tQZvodQCjYfQYukeFSUQDycuIfrZEX78BCOVWCXYN1UkiNtCLXlc7Sifn8hIozHioIDSZXv1R7VWd57xp1HIB/1ru+PJQg9nMYP1CpmY94dPhNfOVlF0J8OZV8gzQKfnjl0JVoW20sIQKabTVr5SVm8OyCVUFPuGQVgg8MBexFeTF/58DupId2lXmKNfgL3bgw4kiSiMNhQpxAZ5Ug+w1kPXQzI+ypobkcTGbGwVpSgz2Ax3hLi8jpVID3BS9L1nqp0a/ouD2l8ueskL1Nj2Pt+e2cLdBKG/0uwk5UfrFf1CYAy0mAjqB9sdOLhuw==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1teBwp-000573-FM; Sat, 01 Feb 2025 06:46:03 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#75981] [PATCH (WIP) v1.5 3/4] Add 'guix fork update'. Resent-From: 45mg <45mg.writes@gmail.com> Original-Sender: "Debbugs-submit" Resent-CC: guix@cbaines.net, dev@jpoiret.xyz, ludo@gnu.org, othacehe@gnu.org, zimon.toutoune@gmail.com, me@tobias.gr, guix-patches@gnu.org Resent-Date: Sat, 01 Feb 2025 11:46:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 75981 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 75981@debbugs.gnu.org Cc: Nicolas Graves , Tomas Volf <~@wolfsden.cz>, 45mg <45mg.writes@gmail.com>, Liliana Marie Prikler , Ricardo Wurmus , Attila Lendvai , Christopher Baines , Josselin Poiret , Ludovic =?utf-8?q?Court=C3=A8s?= , Mathieu Othacehe , Simon Tournier , Tobias Geerinckx-Rice X-Debbugs-Original-Xcc: Christopher Baines , Josselin Poiret , Ludovic =?utf-8?q?Court=C3=A8s?= , Mathieu Othacehe , Simon Tournier , Tobias Geerinckx-Rice Received: via spool by 75981-submit@debbugs.gnu.org id=B75981.173841033119581 (code B ref 75981); Sat, 01 Feb 2025 11:46:03 +0000 Received: (at 75981) by debbugs.gnu.org; 1 Feb 2025 11:45:31 +0000 Received: from localhost ([127.0.0.1]:56718 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1teBwI-00055l-Tm for submit@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:31 -0500 Received: from mail-pl1-x642.google.com ([2607:f8b0:4864:20::642]:42000) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from <45mg.writes@gmail.com>) id 1teBwG-00055U-MY for 75981@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:29 -0500 Received: by mail-pl1-x642.google.com with SMTP id d9443c01a7336-216395e151bso35162275ad.0 for <75981@debbugs.gnu.org>; Sat, 01 Feb 2025 03:45:28 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1738410322; x=1739015122; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=C43SsUA5OCcbVBTaSANAj1vwibNoo1rJF1BpXIfZWW8=; b=frY6YJvA4iv9rrm0t+t1Czox72gYk3SN3nGwlelnG/ceHiipxbz7kbwwR3MKNlrMab VBsCKRg36qzUWtNrFPJXh0kuP4PLnz/mkIjrCrKjs2XFZ+U5A2hX54aNJ/SK8OaG73e5 fy6DdjQLrvmL2HqGnlP4Pg9SobSPIbbnGIvvrRqZuWrFPwfPqWEB841Fj1G8WajqrvLJ CzULuuTTjDkThfQhbm7+oeXpRJeideaarHZmG4JQBea3j8MZgRkb33LvByuQLymvdxhb 4+UdC4KabT4wTWWu83k58Dy+DciKudrobMU3XpvvQO2EWypNejTKVpXNVEXhsp/jxaTi mIIw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738410322; x=1739015122; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=C43SsUA5OCcbVBTaSANAj1vwibNoo1rJF1BpXIfZWW8=; b=YQB96j8eobyrwB5KC4BsQOQm7iSLgC3xe94i+Dw029KhhMxoDQdzCWTgqA4DuHfS0c OQPgcBBWUfMJndvSWximxc6Pg3bgfHVxh/X9QxSBTJ6ANAKymsWWO6Dwjvu+rRNXs0r1 X8iDc5Q9XkTMsUkTeoO7DiY+bz9LbKnK6kJOomWsCH7i1i2qjydD7SjJPwwWCb3DzEjU CatDL6j4Rr5uAI9TsAnmzt5yxhHM3bEvycqzcKSNGnVBtjAraWhWe9mUVcba7kjozBM8 HS+GVnvD6Vfm8U4va2TvnjAQWYfQfCgKUOL2g7wFcD1k4DhEPQDPi/goy0QEwufjbj/x WyVQ== X-Gm-Message-State: AOJu0YzDlTIoJTvaUkr3jXMSZtMufZDKdxM0zMDjvNt05M2FBonl5nMi IiBO1rs+BuvHi83+b/Jaotknm+O5GwGT9O5ZINrfNlfz07D6wNVEcF+hmacm X-Gm-Gg: ASbGncumiDxAHrCBM0oiuzbVRpqw4n5IWvKt1edaxFl3CLPr7EmDzvtgqYvlzRq7yGl 8BDiGVSrMkBfTyfsmCl2xyCA4CqSB7r9guY62D9G9oJkM9/Rh/litW6fvnK8SfKvc6dPL8Poziz EFEQPnbKBbIoj349rFLJ71mu9YRkTNUwProhg3wFmh/J3G0+o2gUr2u16txLQW9HeTWMiRP0fKV V71yLeSOUsr0+Ivq97Kql3NgDJBYkDkCSdJKT6BVxK03KfisT35NF2GZRXqSnXP+wpCPv1oY5Ff GYAX9RC3H2DxBM/GzzyCraTucv2mEYJ/HPJ2PQ== X-Google-Smtp-Source: AGHT+IFbwwKI7Pc2LIZzqmfu9wewH23RfB/o1GVHXun4PgPYResuPVdqO5rRLbnZC0Q2ZbmP/xcQSQ== X-Received: by 2002:a17:902:d486:b0:216:4676:dfb5 with SMTP id d9443c01a7336-21de19b09camr168965575ad.21.1738410322476; Sat, 01 Feb 2025 03:45:22 -0800 (PST) Received: from localhost.localdomain (utm3.nitt.edu. [14.139.162.2]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-21de331f8d4sm43844805ad.224.2025.02.01.03.45.19 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 01 Feb 2025 03:45:22 -0800 (PST) From: 45mg <45mg.writes@gmail.com> Date: Sat, 1 Feb 2025 17:13:25 +0530 Message-ID: <20c828d43d189914c7a5a3de58831f74b134e796.1738408683.git.45mg.writes@gmail.com> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * guix/scripts/fork/update.scm: New file. * Makefile.am (MODULES): Add the new file. * guix/scripts/fork.scm (show-help): Mention new command. (%sub-commands): Add new command. Change-Id: I2017eb9a9286c02ca8bdf962bcbfe89d7607c413 --- Makefile.am | 1 + guix/scripts/fork.scm | 4 +- guix/scripts/fork/update.scm | 182 +++++++++++++++++++++++++++++++++++ 3 files changed, 186 insertions(+), 1 deletion(-) create mode 100644 guix/scripts/fork/update.scm diff --git a/Makefile.am b/Makefile.am index 1c1f5d84fd..8edd371ccd 100644 --- a/Makefile.am +++ b/Makefile.am @@ -380,6 +380,7 @@ MODULES = \ guix/scripts/fork.scm \ guix/scripts/fork/create.scm \ guix/scripts/fork/authenticate.scm \ + guix/scripts/fork/update.scm \ guix/scripts/graph.scm \ guix/scripts/weather.scm \ guix/scripts/container.scm \ diff --git a/guix/scripts/fork.scm b/guix/scripts/fork.scm index c5c7a59ba7..bf9c86e0aa 100644 --- a/guix/scripts/fork.scm +++ b/guix/scripts/fork.scm @@ -32,6 +32,8 @@ (define (show-help) create set up a fork of Guix\n")) (display (G_ "\ authenticate authenticate a fork of Guix\n")) + (display (G_ "\ + update update a fork of Guix\n")) (newline) (display (G_ " -h, --help display this help and exit")) @@ -40,7 +42,7 @@ (define (show-help) (newline) (show-bug-report-information)) -(define %sub-commands '("create" "authenticate")) +(define %sub-commands '("create" "authenticate" "update")) (define (resolve-sub-command name) (let ((module (resolve-interface diff --git a/guix/scripts/fork/update.scm b/guix/scripts/fork/update.scm new file mode 100644 index 0000000000..4223b9855c --- /dev/null +++ b/guix/scripts/fork/update.scm @@ -0,0 +1,182 @@ +;;; GNU Guix --- Functional package management for GNU +;;; Copyright © 2025 Tomas Volf <~@wolfsden.cz> +;;; Copyright © 2025 45mg <45mg.writes@gmail.com> +;;; +;;; This file is part of GNU Guix. +;;; +;;; GNU Guix is free software; you can redistribute it and/or modify it +;;; under the terms of the GNU General Public License as published by +;;; the Free Software Foundation; either version 3 of the License, or (at +;;; your option) any later version. +;;; +;;; GNU Guix is distributed in the hope that it will be useful, but +;;; WITHOUT ANY WARRANTY; without even the implied warranty of +;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +;;; GNU General Public License for more details. +;;; +;;; You should have received a copy of the GNU General Public License +;;; along with GNU Guix. If not, see . + +(define-module (guix scripts fork update) + #:use-module (guix scripts fork authenticate) + #:use-module (git repository) + #:use-module (git structs) + #:use-module (git config) + #:use-module (guix ui) + #:use-module (guix scripts) + #:use-module ((guix utils) #:select (invoke/stdout)) ;TODO move invoke/stdout to (guix build utils) + #:use-module (guix build utils) + #:use-module (guix channels) + #:use-module (ice-9 exceptions) + #:use-module (ice-9 match) + #:use-module (ice-9 popen) + #:use-module (ice-9 pretty-print) + #:use-module (ice-9 string-fun) + #:use-module (ice-9 textual-ports) + #:use-module (srfi srfi-1) + #:use-module (srfi srfi-13) + #:use-module (srfi srfi-26) + #:use-module (srfi srfi-37) + #:use-module (srfi srfi-71) + #:export (guix-fork-update)) + +;;; Commentary: +;;; +;;; Update a fork of Guix created via `guix fork create` and authenticated via +;;; `guix fork authenticate`, by applying new commits from the upstream branch +;;; onto it. +;;; +;;; Code: + +(define %options + ;; Specifications of the command-line options. + (list (option '(#\h "help") #f #f + (lambda args + (show-help) + (exit 0))) + (option '(#\V "version") #f #f + (lambda args + (show-version-and-exit "guix fork create"))) + + (option '( "fork-branch") #t #f + (lambda (opt name arg result) + (alist-cons 'fork-branch-name arg result))) + (option '(#\r "repository") #t #f + (lambda (opt name arg result) + (alist-cons 'directory arg result))))) + +(define %default-options + '()) + +(define %usage + (G_ "Usage: guix fork update [OPTIONS...] +Pull into this Guix fork's configured upstream branch, then apply new commits +onto the current branch. + + -r, --repository=DIRECTORY + Act in the Git repository in DIRECTORY + --fork-branch=BRANCH + Apply new commits onto BRANCH instead of the current + branch + + -h, --help display this help and exit + -V, --version display version information and exit +")) + +(define (show-help) + (display %usage) + (newline) + (show-bug-report-information)) + +(define (missing-arguments) + (leave (G_ "wrong number of arguments; \ +required ~%"))) + + +;;; +;;; Entry point. +;;; + +(define (guix-fork-update . args) + + (define options + (parse-command-line args %options (list %default-options) + #:build-options? #f)) + + (define (command-line-arguments lst) + (reverse (filter-map (match-lambda + (('argument . arg) arg) + (_ #f)) + lst))) + + (define-syntax invoke-git + (lambda (x) + (syntax-case x () + ((_ args ...) + #`(invoke "git" "-C" #,(datum->syntax x 'directory) args ...))))) + + (define-syntax invoke-git/stdout + (lambda (x) + (syntax-case x () + ((_ args ...) + #`(string-trim-right + (invoke/stdout "git" "-C" #,(datum->syntax x 'directory) args ...)))))) + + (with-error-handling + (let* ((directory (or (assoc-ref options 'directory) ".")) + (current-branch-name (invoke-git/stdout + "branch" + "--show-current")) + (current-head-location (invoke-git/stdout + "rev-parse" + "HEAD")) + (fork-branch-name (or (assoc-ref options 'fork-branch-name) + (if (string= current-branch-name "") + (leave (G_ "no current branch and --fork-branch not given")) + current-branch-name))) + + (repository (repository-open directory)) + (upstream-branch-name introduction-commit introduction-signer + (if (fork-configured? repository) + (fork-configured-introduction + (repository-open directory)) + (leave (G_ "fork not fully configured. +(Did you remember to run `guix fork authenticate` first?)%~")))) + (upstream-branch-commit + (invoke-git/stdout "rev-parse" upstream-branch-name)) + (new-upstream-branch-commit "") + (config (repository-config repository)) + (signing-key + (or + (catch 'git-error + (lambda () + (config-entry-value + (config-get-entry config "user.signingkey"))) + (const #f)) + (begin + (info (G_ "user.signingkey not set for this repository.~%")) + (info (G_ "Will attempt to sign commits with fork introduction key.~%")) + introduction-signer)))) + + (info (G_ "Pulling into '~a'...~%") upstream-branch-name) + (invoke-git "switch" upstream-branch-name) + (invoke-git "pull") + (set! new-upstream-branch-commit + (invoke-git/stdout "rev-parse" upstream-branch-name)) + + (info (G_ "Rebasing commits from '~a' to '~a' onto fork branch '~a'...~%") + upstream-branch-commit + new-upstream-branch-commit + fork-branch-name) + (invoke-git "rebase" "--rebase-merges" + (string-append "--gpg-sign=" signing-key) + fork-branch-name new-upstream-branch-commit) + + (info (G_ "Resetting fork branch '~a' to latest rebased commit...~%") + fork-branch-name) + (invoke-git "branch" "--force" fork-branch-name "HEAD") + + (invoke-git "checkout" (or current-branch-name current-head-location)) + + (info (G_ "Successfully updated Guix fork in ~a~%") + directory)))) From patchwork Sat Feb 1 11:43:26 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: 45mg <45mg.writes@gmail.com> X-Patchwork-Id: 38140 Return-Path: X-Original-To: patchwork@mira.cbaines.net Delivered-To: patchwork@mira.cbaines.net Received: by mira.cbaines.net (Postfix, from userid 113) id 2004927BBEA; Sat, 1 Feb 2025 11:46:26 +0000 (GMT) X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on mira.cbaines.net X-Spam-Level: X-Spam-Status: No, score=-6.6 required=5.0 tests=BAYES_00,DKIM_ADSP_CUSTOM_MED, DKIM_SIGNED,DKIM_VALID,FREEMAIL_FROM,MAILING_LIST_MULTI, RCVD_IN_DNSWL_BLOCKED,RCVD_IN_VALIDITY_CERTIFIED,RCVD_IN_VALIDITY_RPBL, RCVD_IN_VALIDITY_SAFE,SPF_HELO_PASS,URIBL_BLOCKED autolearn=ham autolearn_force=no version=3.4.6 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mira.cbaines.net (Postfix) with ESMTPS id 3EE0927BBE2 for ; Sat, 1 Feb 2025 11:46:25 +0000 (GMT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1teBwt-0007LS-FX; Sat, 01 Feb 2025 06:46:07 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1teBwq-0007Kh-OW for guix-patches@gnu.org; Sat, 01 Feb 2025 06:46:04 -0500 Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1teBwq-0005dn-4O; Sat, 01 Feb 2025 06:46:04 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:References:In-Reply-To:Date:From:To:Subject; bh=kTLhP7eOxVAyBixFBetnmK4lTMHiffyZRO+XOSa3nEo=; b=H+9njRyIlPwP0JpHYa+rxLdm9PvWDHM6URNIguvnY+wBma8yWJlMchMXaHADAyh5ESMSna0OkCa85J7h1O+AOqys/OaIcFyUzI0c5O7C4ZS1oTMHi67WMET4UN8UOQ4gniernLoLSvDjEqapNcGBvLz2rF7xzatlhmOyh9R9FO6ZNpQbABXLpCOn5/1eVTk2cmR5WBmIc8t3j2NAK4zITcJ1mERsUHrmk0hCBx0SbZNPTbaJ2WW6UVp1/inw2VJ89S2VEjuR2v3fFA21pQIxJGi0Bd35TZCQYU4bcujzBCAKx/APD1Nrt+MDGWH9fV355VcUTJvW7Sbnb1L8COcRJg==; Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1teBwp-00057D-VQ; Sat, 01 Feb 2025 06:46:03 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#75981] [PATCH (WIP) v1.5 4/4] Document 'guix fork'. Resent-From: 45mg <45mg.writes@gmail.com> Original-Sender: "Debbugs-submit" Resent-CC: ludo@gnu.org, maxim.cournoyer@gmail.com, guix-patches@gnu.org Resent-Date: Sat, 01 Feb 2025 11:46:03 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 75981 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: 75981@debbugs.gnu.org Cc: Nicolas Graves , Tomas Volf <~@wolfsden.cz>, 45mg <45mg.writes@gmail.com>, Liliana Marie Prikler , Ricardo Wurmus , Attila Lendvai , Ludovic =?utf-8?q?Court=C3=A8s?= , Maxim Cournoyer X-Debbugs-Original-Xcc: Ludovic =?utf-8?q?Court=C3=A8s?= , Maxim Cournoyer Received: via spool by 75981-submit@debbugs.gnu.org id=B75981.173841033619598 (code B ref 75981); Sat, 01 Feb 2025 11:46:03 +0000 Received: (at 75981) by debbugs.gnu.org; 1 Feb 2025 11:45:36 +0000 Received: from localhost ([127.0.0.1]:56721 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1teBwN-000561-MD for submit@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:36 -0500 Received: from mail-pl1-x642.google.com ([2607:f8b0:4864:20::642]:60814) by debbugs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.84_2) (envelope-from <45mg.writes@gmail.com>) id 1teBwL-00055a-Ch for 75981@debbugs.gnu.org; Sat, 01 Feb 2025 06:45:34 -0500 Received: by mail-pl1-x642.google.com with SMTP id d9443c01a7336-21654fdd5daso50590765ad.1 for <75981@debbugs.gnu.org>; Sat, 01 Feb 2025 03:45:33 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1738410327; x=1739015127; darn=debbugs.gnu.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=kTLhP7eOxVAyBixFBetnmK4lTMHiffyZRO+XOSa3nEo=; b=CMNPlc3CW9YnyBT1/+HScsq0EDFnNwoDKzOOp9FKDwWj7Pe2hij1ToNAEpuZBeyBaE NYb6Bk4o5phxep0hxZbQJbEWVNjNYIHC8FFpyjoitpL9PVLUB4AiH74kcZ2ZUluQOPM4 iBz56zl8Kvt41FfXVbmucrlBvkLnr3zGLXiaZ1cghDSyIh7vfVw2CRoVsVE4XVrwC4oH jOPLCe//1isx0strjoGgujOSxQNecNxJEg8gcMr84LG3rFM9FR+2VosPdcqbQbW7lsJk eLd4KEJvFuX8omYZ9DEE6E9Zgb9qll2fBNuBLtGJJl91KvbGTIef1Bx5r97YBApqjKC2 JdVw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1738410327; x=1739015127; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=kTLhP7eOxVAyBixFBetnmK4lTMHiffyZRO+XOSa3nEo=; b=Vcm/n+PyiMLBdym/dulhh/kDg1YFGO9L+H7+nYucYb/OkKQWF0znnvCf/zXZBTrqsO ZDn5gMzmD/nzs0QGO28WYKKls3Lu72w5GJKLEYCsLF2y9eHxnNAv82tAqgkHTVTpo+9P IjBhk7u3BiC74CWDYQtKTJkX6E3JVVaPr/Nnf0AOUrAIPWT1ZAnmLMXen24ku2Q2X23H uouveadhlPUqT1l9mw2A5hYgsF+derw3Uu5Ik2ZtwpUUWq1pT8Tz0qUnZxHlJS0c/Ery 5G7IBV6TVoi0e6rzKFEiG9U7XpCTFgLurCxeuIUJ+A9KZu4zIrEiiOeKrFKutyLkxvRW sgcw== X-Gm-Message-State: AOJu0Yx8pisBqQKFBawrF6C2QiQ7uQ2vYeElh0hp1FoqL1bfnJyiNWQ3 CS4uEg+2DU14xKBi1o1vs9vIsskKVD/88ifj/7T1vwxt7mG4/26NY/DCP0ce X-Gm-Gg: ASbGncvWtNPFxTr0wDKPRf6iVAJNgzClSAfLOL5tCo+AtfZ+4kUuexw6L4KrFDyualt mw8lPeD4Hy85SpnDaILT+suuUPYCdX2uoKmJyY5apPXto7oY4WMB0XQE7n+srz+o7KrTD3S7S2A FUuHtcI2WSSxj1tRAEF7BFNmuL+7SyE0Q9JsFpX4/1zMFhR7cxMsyO8uqMNiSIGIY4kOM0fLulD Bv2jG9c+sE/3wijIyjEcDT0K9pAJPzLF5T0zonlawIqwlNMHeW1poezfdIg/J81L+Sl5OwZLzjM GOalT5Ry26tL64IQKtC+4v8AemcFBtzOlmg/jg== X-Google-Smtp-Source: AGHT+IF+4YhbDM5krb8XTSjtwu75EH4CwFw9X+d4yRFSwgufUildNACOeZ6Fw1i/MOM/eJ7oJgRgKg== X-Received: by 2002:a17:902:db03:b0:215:b33b:e26d with SMTP id d9443c01a7336-21dd7c5141fmr216797555ad.21.1738410327178; Sat, 01 Feb 2025 03:45:27 -0800 (PST) Received: from localhost.localdomain (utm3.nitt.edu. [14.139.162.2]) by smtp.gmail.com with ESMTPSA id d9443c01a7336-21de331f8d4sm43844805ad.224.2025.02.01.03.45.24 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 01 Feb 2025 03:45:26 -0800 (PST) From: 45mg <45mg.writes@gmail.com> Date: Sat, 1 Feb 2025 17:13:26 +0530 Message-ID: <49cb491b107b5f0899209905d7679ba389bc65e6.1738408683.git.45mg.writes@gmail.com> X-Mailer: git-send-email 2.48.1 In-Reply-To: References: MIME-Version: 1.0 X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org Sender: guix-patches-bounces+patchwork=mira.cbaines.net@gnu.org X-getmail-retrieved-from-mailbox: Patches * doc/guix.texi (Invoking guix fork): New node. * doc/contributing.texi (Using Your Own Patches): New node. Change-Id: I06240f0fe8d1fe39f27130a72f5d0d92949c99da --- doc/contributing.texi | 50 ++++++++++++++ doc/guix.texi | 150 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 200 insertions(+) diff --git a/doc/contributing.texi b/doc/contributing.texi index c94ae940fa..bd4fd6c2ac 100644 --- a/doc/contributing.texi +++ b/doc/contributing.texi @@ -35,6 +35,7 @@ Contributing * Making Decisions:: Collectively choosing the way forward. * Commit Access:: Pushing to the official repository. * Reviewing the Work of Others:: Some guidelines for sharing reviews. +* Using Your Own Patches:: Using your own work before it's accepted. * Updating the Guix Package:: Updating the Guix package definition. * Deprecation Policy:: Commitments and tools for deprecation. * Writing Documentation:: Improving documentation in GNU Guix. @@ -3095,6 +3096,55 @@ Reviewing the Work of Others have reviewed more easily by adding a @code{reviewed-looks-good} usertag for the @code{guix} user (@pxref{Debbugs Usertags}). +@node Using Your Own Patches +@section Using Your Own Patches + +If you've taken the time to contribute code to Guix, chances are that +you want the changes you've made to be reflected in your own Guix +installation as soon as possible. Maybe you've added a package you want, +and you want to start using it @emph{right now}. Or you've fixed a bug +that affects you, and you want it to @emph{go away}. + +As described in the preceding sections, all contributions to Guix first +go through a review process to ensure code quality. Sometimes, this can +take longer than one would like. Ideally, the pace of the review process +should not prevent you from benefiting from your own work. + +One way to work around this issue is to create an additional channel of +your own (@pxref{Creating a Channel}), and add your code to it. For +certain kinds of contributions, such as adding a new package, this is +fairly straightforward - simply copy your new package definition(s) into +a new file in the channel, and remove them when your contribution is +accepted. + +However, there may be cases where this is not convenient. Certain kinds +of changes, such as those that need to modify existing Guix internals, +may be more challenging to incorporate into a channel. Moreoever, the +more substantial your contribution is, the more work it will be to do +so. + +@cindex fork, of Guix +For such cases, there is another option. Recall that the patch series +that you sent (@pxref{Sending a Patch Series}) was created from a one or +more commits on a checkout of the Guix repository (@pxref{Building from +Git}). You could simply specify this repository (referred to as your +`Guix fork', or simply `fork', from here onwards), and its relevant +branch, as your `@code{guix}' channel (@pxref{Using a Custom Guix +Channel}). Now `@code{guix pull}' will fetch your new commits, and +you'll see the changes you made reflected in your Guix installation! + +However, there's a potential complication to this approach - the issue +of authentication (@pxref{Channel Authentication}). If your fork only +exists on your local filesystem (a `local fork'), then you probably +don't need to worry about this, and can pull without authentication +(@pxref{Invoking guix pull}). But other situations, such as a remotely +hosted fork, may make it important for your fork to be authenticated, in +the same way that all channels are expected to be. + +Guix provides a @command{guix fork} command in order to simplify and +automate many details of creating and managing and authenticated +fork. For more information, @pxref{Invoking guix fork}. + @node Updating the Guix Package @section Updating the Guix Package diff --git a/doc/guix.texi b/doc/guix.texi index b1b6d98e74..bbb5666d0a 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -311,6 +311,7 @@ Top * Invoking guix pack:: Creating software bundles. * The GCC toolchain:: Working with languages supported by GCC. * Invoking guix git authenticate:: Authenticating Git repositories. +* Invoking guix fork:: Creating and managing authenticated forks of Guix. Programming Interface @@ -5930,6 +5931,7 @@ Development * Invoking guix pack:: Creating software bundles. * The GCC toolchain:: Working with languages supported by GCC. * Invoking guix git authenticate:: Authenticating Git repositories. +* Invoking guix fork:: Creating and managing authenticated forks of Guix. @end menu @node Invoking guix shell @@ -7534,6 +7536,154 @@ Invoking guix git authenticate @end table +@node Invoking guix fork +@section Invoking @command{guix fork} + +@cindex @command{guix fork} + +The @command{guix fork} command provides the means to quickly set up, +authenticate, and keep up-to-date an authenticated fork of Guix. For +more information on authentication of a Guix checkout, @pxref{Invoking +guix git authenticate}. + +Its syntax is: + +guix fork ACTION ARGS... + +ACTION specifies the fork-related action to perform. Currently, the +following values are supported: + +@table @code +@item create SIGNING_KEY [DIRECTORY OPTIONS...] +Create a fork of Guix in DIRECTORY, using SIGNING_KEY to sign the introductory +commit. +DIRECTORY defaults to ./guix. + +First, clone Guix into DIRECTORY, unless @code{--use-existing} is +given. Then, add SIGNING_KEY to the `@code{keyring}' branch of the +repository. Finally, create a new `@code{fork}' branch based starting +from the default branch, whose initial commit authorizes SIGNING_KEY +alone (by adding it to @file{.guix-authorizations}) and is signed by it. + +The new `@code{fork}' branch is intended to mirror upstream +Guix. Updating the fork amounts to applying all new commits to it (see +the `@code{update}' command below for further explanation). You can work +on patches in branches based off of this one, in much the same way as +you would base them on Guix's default branch - every commit from the +latter will be present in the former. + +To @command{guix pull} your changes, you could create a `build' branch +starting from the initial fork commit, onto which you can cherry-pick or +rebase commits from patch branches. This branch can then be specified +for the `@code{guix}' channel (@pxref{Using a Custom Guix Channel}). +Updating this channel can be done by merging the `@code{fork}' branch +into it. + +OPTIONS can be one or more of the following: + +@table @code +@item --use-existing +Use existing clone of Guix in DIRECTORY. This is useful if you've +already created commits for a patch series (@pxref{Using Your Own +Patches}). However, all commits to the default branch, as well as any +branches that may be merged into it in the future, must have been signed +with an authorized key; otherwise, authentication will fail later. +@item --upstream=URI +The repository to clone from. This defaults to the default URL for the +Guix repository. +@item --channel-url=URI +Optional URI, which if given, will be used to replace the channel URL. +Furthermore, the existing `origin' remote (which tracks +`@code{upstream}') is renamed to `upstream', and a new `origin' remote +is created to track URI. +@item --git-parameter PARAMETER +Specify configuration PARAMETER for git, via `-c' option. You can pass +this option multiple times. +@end table + +@cindex authentication, of Guix forks +@item authenticate UPSTREAM COMMIT SIGNER [OPTIONS...] +Authenticate a Guix fork, using COMMIT and SIGNER as the fork +introduction. + +First, authenticate new commits from UPSTREAM, using Guix's default +introduction. Then authenticate the remaining commits using the fork +introduction. + +As with @code{guix git authenticate}, all three of UPSTREAM, COMMIT and +SIGNER will be cached in .git/config, so that you don't need to specify +them after the first time. + +OPTIONS can be one or more of the following: + +@table @code +@item --repository=DIRECTORY +@itemx -r DIRECTORY +Authenticate the git repository in DIRECTORY, instead of the current +directory. +@item --upstream-commit=COMMIT +@itemx --upstream-signer=SIGNER +Use COMMIT/SIGNER as the introduction for upstream +Guix, instead of Guix's default channel introduction. +@item --keyring=REFERENCE +@itemx -k REFERENCE +Load keyring for fork commits from REFERENCE, a Git branch (default +`@code{keyring}'). +@item --upstream-keyring=REFERENCE +Load keyring for upstream commits from REFERENCE, a Git branch (default +`@code{keyring}'). +@item --end=COMMIT +Authenticate fork commits up to COMMIT. +@item --upstream-end=COMMIT +Authenticate upstream commits up to COMMIT. + +@item --cache-key=KEY +@itemx --historical-authorizations=FILE +@itemx --stats +Identical to the correponding options in @command{guix git authenticate} +(@pxref{Invoking guix git authenticate}). +@end table + +@item update [OPTIONS...] +Pull into this Guix fork's configured upstream branch (from running +@command{guix fork authenticate}), then apply new commits onto the +current branch. + +This approach may seem less convenient than simply merging the upstream +branch into the fork branch. Indeed, it duplicates every upstream commit +under a different commit hash, and applying a large number of commits +can be slow. However, this is currently the only feasible approach due +to the nature of Guix's authentication mechanism. Namely, merge commits +can only be authenticated if both their parents are signed by an +authorized key, meaning that you can only use the merge workflow if +you're authorized to commit to upstream Guix. + +For mapping commits on the fork branch to their equivalents on the +upstream branch, you can use @command{guix fork identify} (see below). + +OPTIONS can be one or more of the following: + +@table @code +@item --repository=DIRECTORY +@itemx -r DIRECTORY +Act in the Git repository in DIRECTORY. +@item --fork-branch=BRANCH +Apply new commits onto BRANCH instead of the current branch. +@end table + +@item identify +Coming soon! + +Given a commit hash from upstream Guix, print its equivalent on the fork +branch, or vice versa. +This uses the 'Change-Id:' line added to commit messages by Guix's +'commit-msg' hook. +The first invocation of this command will be slow, as the entire set of +corresponding commits is built up as a hash table, and then +cached. Subsequent invocations should be nearly instant. + +@end table + @c ********************************************************************* @node Programming Interface @chapter Programming Interface