Google Season of Docs 2024

Google Season of Docs 2024

[Simon Tournier]

Hi,

( It is when my plate is full that I add more in. :-) )

Google is announcing the Season of Docs.  Somehow, it is similar of
Google Summer of Code but for… wait for it… documentation!

https://opensource.googleblog.com/2024/02/announcing-google-season-of-docs-2024.html

I would like that the Guix project applies as an Organization.  Hence my
message.  Before jumping in the boring paperwork, the first questions
are:

 1. Who does volunteer for being potential mentor?
 2. Would one of you readers be interested by being technical writer?
 3. Any for improving the documentation?

Well, shoot any ideas for #3.  It will help in all cases. :-)

It can range from a one line idea to more elaborated idea; as shown here
[1, 2, 3].

Depending on the feedback, I will create a LibrePlanet webpage or else
and go further in the process. :-)

Last, keep in mind the deadline is less than 10 days from now.

1: https://developers.google.com/season-of-docs/docs/project-ideas
2: https://developers.google.com/season-of-docs/docs/case-study-example
3: https://developers.google.com/season-of-docs/docs/2022/participants

Cheers,
simon

Re: Google Season of Docs 2024

[Attila Lendvai]

> 3. Any for improving the documentation?

just a general wish: much less prose and much more structure, please.

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“There is no coming to consciousness without pain. People will do anything, no matter how absurd, in order to avoid facing their own Soul. One does not become enlightened by imagining figures of light, but by making the darkness conscious. The latter procedure, however, is disagreeable and therefore not popular.”
	— Carl Jung (1875–1961), 'Alchemical Studies' (1967)

Re: Google Season of Docs 2024

[Rostislav Svoboda]

> 3. Any for improving the documentation?

Example snippets for every function. Basically like
https://clojuredocs.org/ but for Guile / Guix.

Thanks in advance.

Re: Google Season of Docs 2024

[Juliana Sims]

Hi Simon,

I would absolutely be interested in actually writing documentation. I 
appear to be rapidly specializing as a technical writer and have long 
wanted to help write better documentation for Guix (and Guile, for that 
matter...). Reimbursement would allow me to set aside the time 
necessary to actually do it.

With the caveat that I may be doing other things at the same time 
(other grants or contracts or who knows; life is unpredictable), I 
would absolutely be interested in doing some actual writing. I don't 
have hard ideas about how to improve the docs so would be tapping folks 
for and accepting feedback.

- Juli (she/her)

Re: Google Season of Docs 2024

[Adam McCartney]

Hi Simon,

First, apologies for being a bit late to the party here!

> 2. Would one of you readers be interested by being technical writer?
> 3. Any for improving the documentation?

I'm quite new to guix, so reading through many docs for the first time and
trying out various workflows. I'm taking notes on the various things that work.
Happy to help with this in any way I can!

In the past I've enjoyed using tutorials like "vimtutor" or emacs' "M-x
help-with-tutorial" when trying to break the ice with a completely new piece of
software. Writing something similar for guix might be fun?

>
>Last, keep in mind the deadline is less than 10 days from now.
>1: https://developers.google.com/season-of-docs/docs/project-ideas
>2: https://developers.google.com/season-of-docs/docs/case-study-example
>3: https://developers.google.com/season-of-docs/docs/2022/participants

Maybe I'm not reading this correctly, but it looks like the application window
opened yesterday, 22nd February and will close for organizations on the 2nd
April 2024?


-- 
  Adam McCartney - https://admccartney.mur.at 
/

Re: Google Season of Docs 2024

[Matt]

[-- Attachment #1: Type: text/plain, Size: 1677 bytes --]


 ---- On Fri, 23 Feb 2024 10:18:33 +0100  Adam McCartney  wrote --- 

 > > 2. Would one of you readers be interested by being technical writer?
 > > 3. Any for improving the documentation?

I'm always interested in improving the Guix documentation.

 > I'm quite new to guix, so reading through many docs for the first time and
 > trying out various workflows. I'm taking notes on the various things that work.

I like this approach of someone new reading through the documentation, taking notes on errors and challenges, and providing a list of findings.  I'm currently working through a thread where someone did just this and we're working through the points one at a time[1].

[1]: https://lists.gnu.org/archive/html/guix-devel/2024-01/msg00117.html

 > In the past I've enjoyed using tutorials like "vimtutor" or emacs' "M-x
 > help-with-tutorial" when trying to break the ice with a completely new piece of
 > software. Writing something similar for guix might be fun?
 
I think a series of case studies which walk through increasingly difficult packaging processes would be a good idea.  It would give new users insight into what the packaging process looks like, would identify common tricks that work across packages, and would highlight problems in the documentation.

I created a template a while back which uses GNU Hello: https://codeberg.org/excalamus/guix-packaging-tutorial/src/branch/master/guix-packaging-tutorial.org#user-content-headline-13

Last month, I started writing a case study for packaging posh, the Policy-compliant Ordinary SHell.  It's incomplete yet will hopefully will give a clearer idea of what I'm thinking.  I've attached it to this email.

[-- Attachment #2: guix-packaging-tutorial-posh.org --]
[-- Type: application/octet-stream, Size: 31717 bytes --]

#+TITLE: Guix Packaging Tutorial: posh
#+DATE: 2024-02-28
#+TOC: t
#+HTML_HEAD: <link rel="stylesheet" type="text/css" href="org.css"/>
#+property: header-args :eval never
# Created: 2024-01-13

<insert top matter here>

* COMMENT Note to authors
** COMMENT Using Emacs Org mode
This document was written in GNU Emacs 29.1 using Org mode version
9.7-pre.  Reading and editing the source is possible using any text
editor.  Org functionality and Lisp functions (likely) require Emacs
version >= 26.  Get Emacs at https://www.gnu.org/software/emacs/.

See [[https://www.gnu.org/software/emacs/manual/html_node/org/Emphasis-and-Monospace.html][Emphasis and Monospace]] for basic Org markup syntax.

Headers are lines beginning with a "*".  Header sections are called
"subtrees."  Collapse header visiblity using =S-TAB= (=M-x
org-shifttab=).  Navigate between headers using =C-c C-n= (=M-x
org-next-visible-heading=) and =C-c C-p= (=M-xd
org-previous-visible-heading=).  Hide all text but the current subtree
using =C-x n s= (=M-x org-narrow-to-subtree=).  Unhide all hidden text
with =C-x n w= (=M-x widen=).  See [[info:emacs#Narrowing][Narrowing]].

Org mode allows executing embeded source code.  Press =C-c C-c= or
call =M-x org-execute-source-block= when the cursor is in a source
block to execute the code.  See [[https://www.gnu.org/software/emacs/manual/html_node/org/Working-with-Source-Code.html][Working with Source Code]].

Write source code contained in blocks marked with the =:tangle= header
argument to disk as standalone files by "tangling" (see section [[* Tangle][Tangle]]
below).

Export this document to Texinfo using =M-x
org-texinfo-export-to-texinfo= (see section [[* Export to Texinfo format][Export to Texinfo format]]
below) and info using =M-x org-texinfo-export-to-info= (see section [[* Export to info
 format][Export to info format]] below).  When using the Emacs info reader, load
an info manual from source using =C-u C-h i
<guix-packaging-tutorial.info>=.  Read the generated info file with
the =info= application using

#+begin_src sh :eval never-export
info ./guix-packaging-tutorial.info
#+end_src

*** COMMENT Tangle
Generate standalone source code files from code blocks.
#+begin_src emacs-lisp :results none :eval never-export
(org-babel-tangle)
#+end_src

*** COMMENT Export to Texinfo format
Convert this document to Texinfo.
#+begin_src emacs-lisp :results none :eval never-export
(org-texinfo-export-to-texinfo)
#+end_src

*** COMMENT Export to info format
Convert this document to info.
#+begin_src emacs-lisp :results none :eval never-export
(org-texinfo-export-to-info)
#+end_src

** COMMENT Convenience functions
*** COMMENT link-to-current-info-node
#+begin_src emacs-lisp
(defun xc/link-to-current-info-node (&optional arg)
  "Create link to current Info node in a variety of formats.

With a negative prefix, place Org link to info node with
description of the current node into the kill ring.

With no prefix, place the url corresponding to the current Info
node into the kill ring.

With universal prefix, visit url with default web browser and do
not put url into the kill ring.

With numeric prefix, place Org link with node name as description
into the kill ring."
  (interactive "p")
  (unless Info-current-node
    (user-error "No current Info node"))
  (let* ((info-file (if (stringp Info-current-file)
                        (file-name-sans-extension
                         (file-name-nondirectory Info-current-file))))
         (node Info-current-node)
         (url (cond
               ((or (string= info-file "emacs") (string= info-file "org") (string= info-file "elisp"))
                (concat "https://www.gnu.org/software/emacs/manual/html_node/"
                        info-file "/"
                        (if (string= node "Top") ""
                          (concat (replace-regexp-in-string " " "-" node t) ".html"))))
               ((string= info-file "guile")
                (concat "https://www.gnu.org/software/guile/manual/html_node/"
                        (if (string= node "Top") ""
                          (concat (replace-regexp-in-string " " "-" node t) ".html"))))
               ((string= info-file "guix")
                (concat "https://guix.gnu.org/en/manual/devel/en/html_node/"
                        (if (string= node "Top") ""
                          (concat (replace-regexp-in-string " " "-" node t) ".html"))))
               )))
    (cond
     ((eq arg -1)  ; -1 prefix
      (kill-new (format "[[info:%s#%s][%s]]" info-file node node))
      (message "%s" (car kill-ring)))
     ((eq arg 1)  ; no prefix
      (kill-new url)
      (message "%s" (car kill-ring)))
     ((eq arg 4)  ; universal prefix
      (browse-url-default-browser url))
     (t           ; any other prefix
      (kill-new (format "[[%s][%s]]" url node))
      (message "%s" (car kill-ring))))))
#+end_src

*** COMMENT buffer-local-abbrevs
An "abbrev" is Emacs jargon for a sequence of characters that expands
(is text replaced) with different text.  For example, rather than
write out "GUIX_PACKAGING_TUTORIAL_WORKDIR" every time, we define a
buffer-local abbrev "gd" which expands to
"GUIX_PACKAGING_TUTORIAL_WORKDIR".

#+begin_src emacs-lisp :results none :eval never-export
(defun my-define-local-abbrev-table (definitions)
  "Define abbrev table with DEFINITIONS local to the current buffer.

Abbrev DEFINITIONS is a list of elements of the form (ABBREVNAME
EXPANSION ...) that are passed to `define-abbrev'.

The local abbrev table has name of the current buffer appended
 with \"-abbrev-table\".

Use `my-clear-local-abbrev-table' to remove local abbrev
definitions."
  (let* ((table-symbol (intern (concat (buffer-name) "-abbrev-table")))) ; inserts in obarray
    (define-abbrev-table table-symbol definitions)
    (setq-local local-abbrev-table (symbol-value table-symbol))
    (message "Created local abbrev table '%s'" table-symbol)))

(defun my-clear-local-abbrev-table ()
  "Clear buffer-local abbrevs.

See `my-define-local-abbrev-table'."
  (let* ((buffer-table-string (concat (buffer-name) "-abbrev-table"))
         (buffer-table-symbol (intern-soft buffer-table-string))        ; nil if not in obarray
         (buffer-table (if buffer-table-symbol
                           (symbol-value buffer-table-symbol))))
    (cond ((abbrev-table-p buffer-table)
           (clear-abbrev-table buffer-table)
           (if (intern-soft buffer-table-string)
               (unintern buffer-table-string))
           (message "Cleared local abbrev table '%s'" buffer-table-string)))))
#+end_src

#+begin_src emacs-lisp :results none :eval never-export
(my-clear-local-abbrev-table)
(my-define-local-abbrev-table
   '(;("abbrev" "expansion" nil :case-fixed t)
     ("gd" "GUIX_PACKAGING_TUTORIAL_WORKDIR")
     ("$gd" "$GUIX_PACKAGING_TUTORIAL_WORKDIR")
    ))
#+end_src

* Introduction
# This should be written last.  However, defining a few things up
# front, such as the intended audience, will help us while writing.

This document details the process of packaging version 0.14.1 of
=posh=, the Policy-compliant Ordinary SHell, for Guix[fn:5].  =posh=
is based on =pdksh=, the Public Domain Korn SHell, and is known for
being POSIX compliant.

The intended audience is...

# ? people interested in software deployment
# ? getting computer programs from one machine to another
# ? developers of software applications and libraries
# ? end-users of software applications and libraries
# ? ...who may become Guix contributors (see comment about packaging binaries)
# ? free software advocates
# ? ...

This tutorial assumes you have the read the Guix [[info:guix#Introduction][Introduction]] and have
either installed [[info:guix#Installation][Guix on a foreign distro]] or use the [[info:guix#System Installation][Guix System]].

Creating a Guix package requires a shell.  It's assumed you have a
basic understanding of shell commands, such as those provided by
=coreutils=[fn:1].  You should feel comfortable with variables and
command substitution.  Know how to use the following help systems:

- ~<command> --help~
- ~man <command>~
- ~info <command>~

This tutorial uses [[info:bash#Top][Bash]].

Guix package definitions are written in GNU Guile, a dialect of
Scheme.  Explaining Guile is beyond the scope of this document.  It is
assumed that you have some familiarity with Lisp and s-expressions.

=git= is used for demonstration purposes and is not required.

Some parts of this tutorial use a web browser in a graphical
environment, although neither is necessary.

* Setup
To begin, let's create a place to work.  The following defines an
environment variable we'll use to reference our working directory.
Note that it uses =/tmp= which is removed each time the computer
reboots.  Change it to something else if you want to keep your work.

#+begin_src sh :results output :exports code :session *guix-tutorial* :eval never-export
# create environment variable
export GUIX_PACKAGING_TUTORIAL_WORKDIR=/tmp/guix-packaging-tutorial

# delete directory if it exists
rm -rf "$GUIX_PACKAGING_TUTORIAL_WORKDIR"

# (re)create directory
mkdir -p "$GUIX_PACKAGING_TUTORIAL_WORKDIR"

# change directory
cd "$GUIX_PACKAGING_TUTORIAL_WORKDIR"

# confirm our location
echo "Current directory: $(pwd)"
#+end_src

#+RESULTS:
: Current directory: /tmp/guix-packaging-tutorial

* Packaging the "Policy-compliant Ordinary SHell"
Guix packages are defined according to the =package= and =origin= data
types[fn:2][fn:3].  The minimal information needed is:

- name
- version
- source URI
- sha256 hash of the source
- build system
- home-page
- synopsis
- description
- license

If you know what you want to build, then you likely have the "name".
The next step is getting the "source URI".

** Locate the source URI
Packages require a "source URI", or string of characters used to name
a resource on the Internet.  For Guix, the resource is typically
source code.  Free software projects distribute source code in
different ways.  Some projects use a version control system, others
provide file bundles (such as =.tar= or =.tar.gz= archives).

At the time of writing, the source code for =posh= is hosted on
Debian's collaborative development server, Salsa[fn:4].  Salsa is a
GitLab forge which uses, unsurprisingly, the =git= version control
system.  Tagged versions are available for download in several
formats, including =.zip=, =.tar.gz=, =.tar.bz=, and =.tar=.

In this case, there are several options for the source: the =git= repo
itself or an archive file.  We'll use an archive file in this
tutorial, although the choice is arbitrary.

The location of source code may not be obvious.  The GitLab web
interface for =posh= requires selecting branches and tags from
drop-down.  The drop-down only shows a tag for "debian/0.14.1" when
pressed[fn:6].  After selecting "debian/0.14.1", we eventually see
that the GitLab web interface has an unlabeled "Download" button.  The
button only shows text on hover[fn:7].  Pressing it reveals four
options: =.zip=, =.tar.gz=, =.tar.bz=, and =.tar=.  Right-click
=.tar.gz= and copy the link.

The source URI for =posh= version 0.14.1 is:

#+begin_example
"https://salsa.debian.org/clint/posh/-/archive/debian/0.14.1/posh-debian-0.14.1.tar.gz"
#+end_example

** Get the hash
Guix builds are often bit-for-bit reproducible.  Users don't need to
trust binaries from the Internet.  They can validate a download by
comparing it to a locally built version.  This is done using
cryptographic hashes, a mathematical method of validation.

A package recipe must contain a hash.  The hash is used to confirm
that the source a user downloads is what the recipe called for.

Use ~guix download~ to calculate the source code hash[fn:8]:

#+begin_src sh :results output :exports both :session *guix-tutorial* :async t :eval never-export
guix download https://salsa.debian.org/clint/posh/-/archive/debian/0.14.1/posh-debian-0.14.1.tar.gz
#+end_src

#+RESULTS:
: Starting download of /tmp/guix-file.VsmK2d
: From https://salsa.debian.org/clint/posh/-/archive/debian/0.14.1/posh-debian-0.14.1.tar.gz...
:  …0.14.1.tar.gz  243KiB                                       409KiB/s 00:01 ▕██████████████████▏ 100.0%
: /gnu/store/asdk74a88qm06wancqcqm2mcczd5gpmn-posh-debian-0.14.1.tar.gz
: 070xnn996cjnc5yzp5819y36sgfikkrplhri4kx5r36h1fmp641d

The source code hash for =posh= 0.14.1 is:

#+begin_example
"070xnn996cjnc5yzp5819y36sgfikkrplhri4kx5r36h1fmp641d"
#+end_example

** Identify the build system
The next step after finding the source code is to identify the build
system[fn:9].  Hopefully the authors left a note about how to build
the project!

For demonstration purposes, we clone the =posh= repository and
checkout version 0.14.1.

#+begin_src sh :results output :exports both :session *guix-tutorial* :async t :eval never-export
# clone source code
git clone https://salsa.debian.org/clint/posh.git

# enter repository directory
cd posh && echo "Current directory: $(pwd)"

# checkout source code corresponding to version 0.14.1
git -c advice.detachedHead=false checkout debian/0.14.1
#+end_src

#+RESULTS:
: Cloning into 'posh'...
: remote: Enumerating objects: 1318, done.
: remote: Total 1318 (delta 0), reused 0 (delta 0), pack-reused 1318
: Receiving objects: 100% (1318/1318), 464.78 KiB | 637.00 KiB/s, done.
: Resolving deltas: 100% (904/904), done.
: Current directory: /tmp/guix-packaging-tutorial/posh
: HEAD is now at 78fabd8 changelog for 0.14.1

Unfortunately, =posh= doesn't have build instructions.  There is no
README, website, or comment explaining how to "build" or "install"
=posh=.  With no build instructions, we must guess.

One trick is to =grep= the source code for build related words, like
"build" or "install."

#+begin_src sh :results output :exports both :session *guix-tutorial* :async t :eval never-export
grep -rn -e "build" -e "install"
#+end_src

#+RESULTS:
#+begin_example
posh.xml:138:		The meta-characters are used in building the following tokens:
posh.xml:174:	    <para>As words and tokens are parsed, the shell builds commands, of which
configure.ac:44:dnl  Specify what kind of shell we are to build.  Options are ksh and sh.
.gitignore:8:install-sh
.git/hooks/pre-rebase.sample:102:   it is deleted.  If you need to build on top of it to correct
.git/hooks/pre-rebase.sample:125:    build on top of it -- other people may already want to
.git/hooks/sendemail-validate.sample:42:	# (e.g. quick build, coding style checks, etc.).
COPYING:159:control compilation and installation of the executable.  However, as a
debian/po/de.po:32:msgstr "posh als /bin/sh installieren?"
debian/changelog:44:    thus obviating build dependency on libperl4-corelibs-perl.
debian/changelog:53:  * Suppress linemarker generation when building signal table, as
debian/changelog:63:  * Patch from Chris Lamb to make the build reproducible.
debian/changelog:79:  * Add libperl4-corelibs-perl build-dep for getopts.pl.
debian/changelog:106:  * Patch from Stefano Rivera to build with eglibc 2.16.  closes: #692537.
debian/changelog:122:  * Fix "nostrip" build.  closes: #674703.
debian/changelog:131:  * Use dpkg-buildflags.
debian/changelog:132:  * Add build-arch and build-indep targets.
debian/changelog:147:  * Fix build-time signal list generation.  closes: #612844.
debian/changelog:643:  * Add prebuild target to debian/rules.
debian/changelog:829:    sbuild.  closes: #181305.
debian/changelog:858:  * Run "make check" as part of build.
debian/changelog:893:  * Add build-dep on debconf-utils.
debian/changelog:914:  * Remove debhelper stuff.  Now no build-deps outside of build-essential.
debian/changelog:920:  * Put build system under automake.
debian/changelog:974:  * Separate configure target from build target in debian/rules.
debian/posh.postinst:3:# post-install script for the Debian GNU/Linux posh package
debian/rules:4:	dh $@ --builddirectory=obj --with=autoreconf
debian/rules:8:prebuild:
debian/rules:13:.PHONY: prebuild
posh.1:116:))\&. Aside from delimiting words, spaces and tabs are ignored, while newlines usually delimit commands\&. The meta\-characters are used in building the following tokens:
posh.1:177:As words and tokens are parsed, the shell builds commands, of which there are two basic types:
#+end_example

Reading carefully, we find an important clue.  A line reads, "Put
build system under automake."  Automake is a compilation tool for the
GNU Build System, also called "Autotools."[fn:10][fn:11]

We find further evidence for the GNU Build System in the top-level
directory.  There are several files ending in ".ac", ".m4", and ".ac".

#+begin_src sh :results output :exports both :session *guix-tutorial* :async t
find . -maxdepth 1 -name "*.ac" -or -name "*.am" -or -name "*.m4"
#+end_src

#+RESULTS:
: ./acinclude.m4
: ./Makefile.am
: ./configure.ac

These files are associated with Autotools.

Recognizing a project's use of Autotools simply comes from experience.
Now that you have some, this knowledge is part of your repertoire!  If
you're unfamiliar with Autotools, it's worth the time to read through
its documentation.[fn:12] Autotools is an important and common build
system.

After a little investigation, it seems that =posh= is built using GNU
Autotools.

** Figure out the license
The only remaining requirement worth comment is the license.

The Guix System maintains a prestigious endorsement from the Free
Software Foundation for being made entirely of libre software.  Libre
software empowers users by respecting the Four Freedoms:

- The freedom to run the program as you wish, for any purpose
- The freedom to study how the program works, and change it so it does
  your computing as you wish
- The freedom to redistribute copies
- The freedom to distribute modified copies

A comprehensive list of libre licenses is maintained by the GNU
project[fn:13].  Guix maintains an internal registry of licenses based
on the GNU list within =guix/licenses.scm=[fn:14].

Most licenses require that a copy of the license be provided along
with the source code.  License files are often called COPYING or
LICENSE.  Sometimes no separate file exists and a header is used
within code files.  Other times only a reference is given and the
license text posted elsewhere.  As with source code, you may need to
look around a bit.

=posh= includes a COPYING file:

#+begin_src sh :results output :exports both :session *guix-tutorial* :async t :eval never-export
ls | grep COPYING
#+end_src

#+RESULTS:
: COPYING

It tells us that the license is GPLv2:

#+begin_src sh :results output :exports both :session *guix-tutorial* :async t :eval never-export
head -n2 COPYING
#+end_src

#+RESULTS:
:                   GNU GENERAL PUBLIC LICENSE
:                      Version 2, June 1991

** Incrementally defining a package
With the minimal package requirements handy, we can make a first
attempt at a package definition.  It may take multiple attempts to get
the definition to build and that's normal.

# *The different ways to build a package*
There are 4 ways to build a package:

1. =guix package --install-from-file=my-package-definition.scm=
2. =guix build --file=my-package-definition.scm=
3. =guix build --load-path ./ module-name-that-is-also-the-file-name=
4. within the Guile interpreter

   #+begin_example
   scheme@(guile-user)> ,use (guix)
   scheme@(guile-user)> (use-modules (guix packages)
                   (guix download)
                   (guix build-system gnu)
                   (gnu packages autotools)
                   (gnu packages perl)
                   ((guix licenses) #:prefix license:))
   scheme@(guile-user)> (package
          (name "posh")
          (version "0.14.1")
          (source (origin
                    (method url-fetch)
                    (uri (string-append
                          "https://salsa.debian.org/clint/posh/-/archive/debian/"
                          version "/posh-debian-" version ".tar.gz"))
                    (sha256
                     (base32
                      "070xnn996cjnc5yzp5819y36sgfikkrplhri4kx5r36h1fmp641d"))))
          (native-inputs (list autoconf automake perl))
          (build-system gnu-build-system)
          (home-page "https://salsa.debian.org/clint/posh")
          (synopsis "Policy-compliant Ordinary SHell")
          (description
           "Policy-compliant Ordinary SHell
      posh is a stripped-down version of pdksh that aims for compliance with
      Debian's policy, and few extra features.")
          (license (list license:gpl2+)))
   $5 = #<package posh@0.14.1 7f0e8e5ea9a0>
   scheme@(guile-user)> ,build $5
   $6 = "/gnu/store/64wiqdp9lqjgsz0jg1v1sq2b3afincrb-posh-0.14.1"
   #+end_example

*Minimal definition*
The Guix documentation has several examples of a package definition
and the Guix source code contains many more.

#+begin_src scheme :results output :exports code :tangle (format "%s" "/tmp/guix-packaging-tutorial/posh-draft-01.scm") :eval never-export
;;; posh-draft-01.scm --- Package definition for GNU Guix
(use-modules
 (guix packages)          ; provides the 'package' and 'origin' data types
 (guix download)          ; provides 'url-fetch' procedure
 (guix build-system gnu)
 ((guix licenses) #:prefix license:))

(define-public posh
  (package
    (name "posh")
    (version "0.14.1")
    (source (origin
              (method url-fetch)
              (uri (string-append
                    "https://salsa.debian.org/clint/posh/-/archive/debian/"
                    version "/posh-debian-" version ".tar.gz"))
              (sha256
               (base32
                "070xnn996cjnc5yzp5819y36sgfikkrplhri4kx5r36h1fmp641d"))))
    (build-system gnu-build-system)
    (home-page "https://salsa.debian.org/clint/posh")
    (synopsis "Policy-compliant Ordinary SHell")
    (description
     "Policy-compliant Ordinary SHell
posh is a stripped-down version of pdksh that aims for compliance with
Debian's policy, and few extra features.")
    (license (list license:gpl2))))

posh
;;; posh-draft-01.scm ends here
#+end_src

#+begin_src sh :results output :exports both :session *guix-tutorial* :async t :eval never-export
guix build -f posh-draft-01.scm
#+end_src

#+RESULTS:
#+begin_example
The following derivation will be built:
  /gnu/store/a1pwx6rq36a2i8jffx76nqzbbx3x4hd9-posh-0.14.1.drv
building /gnu/store/a1pwx6rq36a2i8jffx76nqzbbx3x4hd9-posh-0.14.1.drv...
starting phase `set-SOURCE-DATE-EPOCH'
phase `set-SOURCE-DATE-EPOCH' succeeded after 0.0 seconds
starting phase `set-paths'
environment variable `PATH' set to `/gnu/store/sxx22f98vfbavcqmdksm6as8fvskpxiw-tar-1.34/bin:/gnu/store/x24bm49ag5dvki72mjdz195bfb89nrnb-gzip-1.12/bin:/gnu/store/j8wlfmlmfvpbza6is9wv9xsd8psrxn00-bzip2-1.0.8/bin:/gnu/store/gr0sy0m1mv36qv54idm6cn10l3mngshq-file-5.44/bin:/gnu/store/zmcf5kpqiighkbh7wslf91qdjwj06yr1-diffutils-3.8/bin:/gnu/store/210yfax18r2g2inxrml9435ikhfcca6m-patch-2.7.6/bin:/gnu/store/c8jyph2lxw0m9na34fg8h70n4nnnz7is-findutils-4.9.0/bin:/gnu/store/hc05d76f1j3iz3v2bs5jz4fpljl1r4dj-gawk-5.2.1/bin:/gnu/store/xxcfsimvxz7z4dj593gnqbkzc6picwzq-sed-4.8/bin:/gnu/store/yrv5f70mn83a876b78i5s79dd2hsh0zf-grep-3.8/bin:/gnu/store/6k1yys9wqrfn4y41ic1win8gpnimncwj-xz-5.2.8/bin:/gnu/store/a5i8avx826brw5grn3n4qv40g514505c-coreutils-9.1/bin:/gnu/store/wj7casda7rb55rvqjnpm0bm7a2zm6618-make-4.3/bin:/gnu/store/rib9g2ig1xf3kclyl076w28parmncg4k-bash-minimal-5.1.16/bin:/gnu/store/na1dpbbcxjaa3n8wkwrfpch476f90hlf-ld-wrapper-0/bin:/gnu/store/zh4x65snfis7svs6906gj1z8i7dx2j3m-binutils-2.38/bin:/gnu/store/5lqhcv91ijy82p92ac6g5xw48l0lwwz4-gcc-11.3.0/bin:/gnu/store/gsjczqir1wbz8p770zndrpw4rnppmxi3-glibc-2.35/bin:/gnu/store/gsjczqir1wbz8p770zndrpw4rnppmxi3-glibc-2.35/sbin'
environment variable `BASH_LOADABLES_PATH' unset
environment variable `C_INCLUDE_PATH' set to `/gnu/store/j8wlfmlmfvpbza6is9wv9xsd8psrxn00-bzip2-1.0.8/include:/gnu/store/gr0sy0m1mv36qv54idm6cn10l3mngshq-file-5.44/include:/gnu/store/hc05d76f1j3iz3v2bs5jz4fpljl1r4dj-gawk-5.2.1/include:/gnu/store/6k1yys9wqrfn4y41ic1win8gpnimncwj-xz-5.2.8/include:/gnu/store/wj7casda7rb55rvqjnpm0bm7a2zm6618-make-4.3/include:/gnu/store/zh4x65snfis7svs6906gj1z8i7dx2j3m-binutils-2.38/include:/gnu/store/5lqhcv91ijy82p92ac6g5xw48l0lwwz4-gcc-11.3.0/include:/gnu/store/gsjczqir1wbz8p770zndrpw4rnppmxi3-glibc-2.35/include:/gnu/store/5iklcps70c0sfkxvlrhg8jhf3q4h18bj-linux-libre-headers-5.15.49/include'
environment variable `CPLUS_INCLUDE_PATH' set to `/gnu/store/j8wlfmlmfvpbza6is9wv9xsd8psrxn00-bzip2-1.0.8/include:/gnu/store/gr0sy0m1mv36qv54idm6cn10l3mngshq-file-5.44/include:/gnu/store/hc05d76f1j3iz3v2bs5jz4fpljl1r4dj-gawk-5.2.1/include:/gnu/store/6k1yys9wqrfn4y41ic1win8gpnimncwj-xz-5.2.8/include:/gnu/store/wj7casda7rb55rvqjnpm0bm7a2zm6618-make-4.3/include:/gnu/store/zh4x65snfis7svs6906gj1z8i7dx2j3m-binutils-2.38/include:/gnu/store/5lqhcv91ijy82p92ac6g5xw48l0lwwz4-gcc-11.3.0/include/c++:/gnu/store/5lqhcv91ijy82p92ac6g5xw48l0lwwz4-gcc-11.3.0/include:/gnu/store/gsjczqir1wbz8p770zndrpw4rnppmxi3-glibc-2.35/include:/gnu/store/5iklcps70c0sfkxvlrhg8jhf3q4h18bj-linux-libre-headers-5.15.49/include'
environment variable `LIBRARY_PATH' set to `/gnu/store/j8wlfmlmfvpbza6is9wv9xsd8psrxn00-bzip2-1.0.8/lib:/gnu/store/gr0sy0m1mv36qv54idm6cn10l3mngshq-file-5.44/lib:/gnu/store/hc05d76f1j3iz3v2bs5jz4fpljl1r4dj-gawk-5.2.1/lib:/gnu/store/6k1yys9wqrfn4y41ic1win8gpnimncwj-xz-5.2.8/lib:/gnu/store/zh4x65snfis7svs6906gj1z8i7dx2j3m-binutils-2.38/lib:/gnu/store/gsjczqir1wbz8p770zndrpw4rnppmxi3-glibc-2.35/lib:/gnu/store/l0yryi5jsa1grnvw01c9nkz9c81cv224-glibc-2.35-static/lib:/gnu/store/visfdda934gvivwihwhlm63fdqhhcc8a-glibc-utf8-locales-2.35/lib'
environment variable `GUIX_LOCPATH' set to `/gnu/store/visfdda934gvivwihwhlm63fdqhhcc8a-glibc-utf8-locales-2.35/lib/locale'
phase `set-paths' succeeded after 0.0 seconds
starting phase `install-locale'
using 'en_US.utf8' locale for category "LC_ALL"
phase `install-locale' succeeded after 0.0 seconds
starting phase `unpack'
posh-debian-0.14.1/
posh-debian-0.14.1/COPYING
posh-debian-0.14.1/Makefile.am
posh-debian-0.14.1/acinclude.m4
posh-debian-0.14.1/alloc.c
posh-debian-0.14.1/c_test.c
posh-debian-0.14.1/c_test.h
posh-debian-0.14.1/conf-end.h
posh-debian-0.14.1/configure.ac
posh-debian-0.14.1/debian/
posh-debian-0.14.1/debian/changelog
posh-debian-0.14.1/debian/control
posh-debian-0.14.1/debian/copyright
posh-debian-0.14.1/debian/menu
posh-debian-0.14.1/debian/po/
posh-debian-0.14.1/debian/po/POTFILES.in
posh-debian-0.14.1/debian/po/cs.po
posh-debian-0.14.1/debian/po/da.po
posh-debian-0.14.1/debian/po/de.po
posh-debian-0.14.1/debian/po/es.po
posh-debian-0.14.1/debian/po/fr.po
posh-debian-0.14.1/debian/po/it.po
posh-debian-0.14.1/debian/po/ja.po
posh-debian-0.14.1/debian/po/nl.po
posh-debian-0.14.1/debian/po/pt.po
posh-debian-0.14.1/debian/po/pt_BR.po
posh-debian-0.14.1/debian/po/ru.po
posh-debian-0.14.1/debian/po/sv.po
posh-debian-0.14.1/debian/po/templates.pot
posh-debian-0.14.1/debian/posh.config
posh-debian-0.14.1/debian/posh.postinst
posh-debian-0.14.1/debian/posh.postrm
posh-debian-0.14.1/debian/posh.prerm
posh-debian-0.14.1/debian/posh.templates
posh-debian-0.14.1/debian/rules
posh-debian-0.14.1/debian/source/
posh-debian-0.14.1/debian/source/format
posh-debian-0.14.1/debian/tests/
posh-debian-0.14.1/debian/tests/control
posh-debian-0.14.1/debian/tests/smoke
posh-debian-0.14.1/edit.h
posh-debian-0.14.1/eval.c
posh-debian-0.14.1/exec.c
posh-debian-0.14.1/expand.h
posh-debian-0.14.1/expr.c
posh-debian-0.14.1/history.c
posh-debian-0.14.1/io.c
posh-debian-0.14.1/jobs.c
posh-debian-0.14.1/ksh_dir.h
posh-debian-0.14.1/ksh_limval.h
posh-debian-0.14.1/ksh_stat.h
posh-debian-0.14.1/ksh_time.h
posh-debian-0.14.1/ksh_wait.h
posh-debian-0.14.1/lex.c
posh-debian-0.14.1/lex.h
posh-debian-0.14.1/main.c
posh-debian-0.14.1/misc.c
posh-debian-0.14.1/path.c
posh-debian-0.14.1/posh.1
posh-debian-0.14.1/posh.xml
posh-debian-0.14.1/proto.h
posh-debian-0.14.1/sh.h
posh-debian-0.14.1/shf.c
posh-debian-0.14.1/shf.h
posh-debian-0.14.1/siglist.in
posh-debian-0.14.1/siglist.sh
posh-debian-0.14.1/src/
posh-debian-0.14.1/src/Makefile.am
posh-debian-0.14.1/src/builtins.c
posh-debian-0.14.1/src/compat.c
posh-debian-0.14.1/src/compat.h
posh-debian-0.14.1/src/times.c
posh-debian-0.14.1/syn.c
posh-debian-0.14.1/table.c
posh-debian-0.14.1/table.h
posh-debian-0.14.1/tests/
posh-debian-0.14.1/tests/Makefile.am
posh-debian-0.14.1/tests/README
posh-debian-0.14.1/tests/arithmetic.t
posh-debian-0.14.1/tests/error.t
posh-debian-0.14.1/tests/exec.t
posh-debian-0.14.1/tests/expand.t
posh-debian-0.14.1/tests/mksh.t
posh-debian-0.14.1/tests/nonposix.t
posh-debian-0.14.1/tests/parameters.t
posh-debian-0.14.1/tests/quoting.t
posh-debian-0.14.1/tests/th
posh-debian-0.14.1/tests/th-sh
posh-debian-0.14.1/tests/token.t
posh-debian-0.14.1/tests/trap.t
posh-debian-0.14.1/tests/utilities.t
posh-debian-0.14.1/tests/variables.t
posh-debian-0.14.1/tests/version.t
posh-debian-0.14.1/trap.c
posh-debian-0.14.1/tree.c
posh-debian-0.14.1/tree.h
posh-debian-0.14.1/tty.c
posh-debian-0.14.1/tty.h
posh-debian-0.14.1/var.c
phase `unpack' succeeded after 0.0 seconds
starting phase `bootstrap'
In execvp of autoreconf: No such file or directory
error: in phase 'bootstrap': uncaught exception:
%exception #<&invoke-error program: "autoreconf" arguments: ("-vif") exit-status: 127 term-signal: #f stop-signal: #f>
phase `bootstrap' failed after 0.0 seconds
command "autoreconf" "-vif" failed with status 127
builder for `/gnu/store/a1pwx6rq36a2i8jffx76nqzbbx3x4hd9-posh-0.14.1.drv' failed with exit code 1
build of /gnu/store/a1pwx6rq36a2i8jffx76nqzbbx3x4hd9-posh-0.14.1.drv failed
View build log at '/var/log/guix/drvs/a1/pwx6rq36a2i8jffx76nqzbbx3x4hd9-posh-0.14.1.drv.gz'.
guix build: error: build of `/gnu/store/a1pwx6rq36a2i8jffx76nqzbbx3x4hd9-posh-0.14.1.drv' failed
#+end_example

* File Variables :noexport:
The following adds a hook which updates the date line (beginning with
"#+DATE") at the top of this file whenever it is saved.
# Local Variables:
# time-stamp-start: "^\\#\\+[Dd]+[Aa]+[Tt]+[Ee]+:[  ]+"
# time-stamp-end: "\\\\?$"
# time-stamp-format:"%Y-%02m-%02d"
# eval: (add-hook 'before-save-hook 'time-stamp nil t)
# End:

* Footnotes

[fn:1] https://www.gnu.org/software/coreutils/manual/html_node/index.html

[fn:2] https://guix.gnu.org/en/manual/devel/en/html_node/package-Reference.html

[fn:3] https://guix.gnu.org/en/manual/devel/en/html_node/origin-Reference.html

[fn:4] https://salsa.debian.org/clint/posh

[fn:5] https://web.archive.org/web/20240113134519/https://packages.debian.org/stable/posh

[fn:6] https://salsa.debian.org/clint/posh/-/tree/debian/0.14.1?ref_type=tags

[fn:7] By the time you read this, the webpage may have changed.  While
       some of this may appear obvious, finding the source often
       requires a bit of searching.  This example demonstrates that
       the location of the URI may not be clearly labeled, or even
       labeled at all!

[fn:8] https://guix.gnu.org/en/manual/devel/en/html_node/Invoking-guix-download.html

[fn:9] https://guix.gnu.org/en/manual/devel/en/html_node/Build-Systems.html

[fn:10] https://www.gnu.org/software/automake/manual/automake.html

[fn:11] https://www.gnu.org/software/automake/manual/html_node/Introduction.html

[fn:12] https://www.gnu.org/software/automake/manual/html_node/Autotools-Introduction.html

[fn:13] https://www.gnu.org/licenses/license-list

[fn:14] https://git.savannah.gnu.org/cgit/guix.git/tree/guix/licenses.scm#n41

[fn:15] https://www.catb.org/~esr/faqs/smart-questions.html#before

[fn:16] https://slash7.com/2006/12/22/vampires/

[fn:17] Unless you provided the definition for GNU Hello.  That's
        included with Guix so it doesn't have this problem.