aboutsummaryrefslogtreecommitdiff
@node Contributing @chapter Contributing This project is a cooperative effort, and we need your help to make it grow! Please get in touch with us on @email{guix-devel@@gnu.org} and @code{#guix} on the Libera Chat IRC network. We welcome ideas, bug reports, patches, and anything that may be helpful to the project. We particularly welcome help on packaging (@pxref{Packaging Guidelines}). @cindex code of conduct, of contributors @cindex contributor covenant We want to provide a warm, friendly, and harassment-free environment, so that anyone can contribute to the best of their abilities. To this end our project uses a ``Contributor Covenant'', which was adapted from @url{https://contributor-covenant.org/}. You can find a local version in the @file{CODE-OF-CONDUCT} file in the source tree. Contributors are not required to use their legal name in patches and on-line communication; they can use any name or pseudonym of their choice. @menu * Requirements:: Software needed to build and run Guix. * Building from Git:: The latest and greatest. * Running the Test Suite:: Testing Guix. * Running Guix Before It Is Installed:: Hacker tricks. * The Perfect Setup:: The right tools. * Alternative Setups:: Other possible tools that do the job. * Source Tree Structure:: Source code guided tour. * Packaging Guidelines:: Growing the distribution. * Coding Style:: Hygiene of the contributor. * Submitting Patches:: Share your work. * Tracking Bugs and Changes:: Keeping it all organized. * Commit Access:: Pushing to the official repository. * Reviewing the Work of Others:: Some guidelines for sharing reviews. * Updating the Guix Package:: Updating the Guix package definition. * Writing Documentation:: Improving documentation in GNU Guix. * Translating Guix:: Make Guix speak your native language. @end menu @node Requirements @section Requirements You can easily hack on Guix itself using Guix and Git, which we use for version control (@pxref{Building from Git}). But when packaging Guix for foreign distros or when bootstrapping on systems without Guix, and if you decide to not just trust and install our readily made binary (@pxref{Binary Installation}), you can download a release version of our reproducible source tarball and read on. This section lists requirements when building Guix from source. The build procedure for Guix is the same as for other GNU software, and is not covered here. Please see the files @file{README} and @file{INSTALL} in the Guix source tree for additional details. @cindex official website GNU Guix is available for download from its website at @url{https://www.gnu.org/software/guix/}. GNU Guix depends on the following packages: @itemize @item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x, version 3.0.3 or later; @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version 0.1.0 or later; @item @uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile Preparations, how to install the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to @uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS until version 3.7.8 included.}; @item @uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0 or later; @item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib}, version 0.1.0 or later; @item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib}; @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi}; @item @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0 or later; @item @uref{https://git-scm.com, Git} (yes, both!); @item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON} 4.3.0 or later; @item @url{https://www.gnu.org/software/make/, GNU Make}. @end itemize The following dependencies are optional: @itemize @item @c Note: We need at least 0.13.0 for #:nodelay. Support for build offloading (@pxref{Daemon Offload Setup}) and @command{guix copy} (@pxref{Invoking guix copy}) depends on @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, version 0.13.0 or later. @item @uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd compression and decompression in @command{guix publish} and for substitutes (@pxref{Invoking guix publish}). @item @uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for the @code{crate} importer (@pxref{Invoking guix import}). @item @uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for the @code{go} importer (@pxref{Invoking guix import}) and for some of the ``updaters'' (@pxref{Invoking guix refresh}). @item When @url{http://www.bzip.org, libbz2} is available, @command{guix-daemon} can use it to compress build logs. @end itemize Unless @option{--disable-daemon} was passed to @command{configure}, the following packages are also needed: @itemize @item @url{https://gnupg.org/, GNU libgcrypt}; @item @url{https://sqlite.org, SQLite 3}; @item @url{https://gcc.gnu.org, GCC's g++}, with support for the C++11 standard. @end itemize @node Building from Git @section Building from Git If you want to hack Guix itself, it is recommended to use the latest version from the Git repository: @example git clone https://git.savannah.gnu.org/git/guix.git @end example @cindex authentication, of a Guix checkout How do you ensure that you obtained a genuine copy of the repository? To do that, run @command{guix git authenticate}, passing it the commit and OpenPGP fingerprint of the @dfn{channel introduction} (@pxref{Invoking guix git authenticate}): @c The commit and fingerprint below must match those of the channel @c introduction in '%default-channels'. @example git fetch origin keyring:keyring guix git authenticate 9edb3f66fd807b096b48283debdcddccfea34bad \ "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" @end example @noindent This command completes with exit code zero on success; it prints an error message and exits with a non-zero code otherwise. As you can see, there is a chicken-and-egg problem: you first need to have Guix installed. Typically you would install Guix System (@pxref{System Installation}) or Guix on top of another distro (@pxref{Binary Installation}); in either case, you would verify the OpenPGP signature on the installation medium. This ``bootstraps'' the trust chain. The easiest way to set up a development environment for Guix is, of course, by using Guix! The following command starts a new shell where all the dependencies and appropriate environment variables are set up to hack on Guix: @example guix shell -D guix -CPW @end example or even, from within a Git worktree for Guix: @example guix shell -CPW @end example If @option{-C} (short for @option{--container}) is not supported on your system, try @command{--pure} instead of @option{-CPW}. @xref{Invoking guix shell}, for more information on that command. If you are unable to use Guix when building Guix from a checkout, the following are the required packages in addition to those mentioned in the installation instructions (@pxref{Requirements}). @itemize @item @url{https://gnu.org/software/autoconf/, GNU Autoconf}; @item @url{https://gnu.org/software/automake/, GNU Automake}; @item @url{https://gnu.org/software/gettext/, GNU Gettext}; @item @url{https://gnu.org/software/texinfo/, GNU Texinfo}; @item @url{https://www.graphviz.org/, Graphviz}; @item @url{https://www.gnu.org/software/help2man/, GNU Help2man (optional)}. @end itemize On Guix, extra dependencies can be added by instead running @command{guix shell}: @example guix shell -D guix help2man git strace --pure @end example From there you can generate the build system infrastructure using Autoconf and Automake: @example ./bootstrap @end example If you get an error like this one: @example configure.ac:46: error: possibly undefined macro: PKG_CHECK_MODULES @end example @noindent it probably means that Autoconf couldn’t find @file{pkg.m4}, which is provided by pkg-config. Make sure that @file{pkg.m4} is available. The same holds for the @file{guile.m4} set of macros provided by Guile. For instance, if you installed Automake in @file{/usr/local}, it wouldn’t look for @file{.m4} files in @file{/usr/share}. In that case, you have to invoke the following command: @example export ACLOCAL_PATH=/usr/share/aclocal @end example @xref{Macro Search Path,,, automake, The GNU Automake Manual}, for more information. @cindex state directory @cindex localstatedir @cindex system configuration directory @cindex sysconfdir Then, run: @example ./configure @end example @noindent ... where @file{/var} is the normal @code{localstatedir} value (@pxref{The Store}, for information about this) and @file{/etc} is the normal @code{sysconfdir} value. Note that you will probably not run @command{make install} at the end (you don't have to) but it's still important to pass the right @code{localstatedir} and @code{sysconfdir} values, which get recorded in the @code{(guix config)} Guile module. Finally, you can build Guix and, if you feel so inclined, run the tests (@pxref{Running the Test Suite}): @example make make check @end example @noindent If anything fails, take a look at installation instructions (@pxref{Installation}) or send a message to the @email{guix-devel@@gnu.org, mailing list}. From there on, you can authenticate all the commits included in your checkout by running: @example guix git authenticate \ 9edb3f66fd807b096b48283debdcddccfea34bad \ "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" @end example The first run takes a couple of minutes, but subsequent runs are faster. On subsequent runs, you can run the command without any arguments since the @dfn{introduction} (the commit ID and OpenPGP fingerprints above) will have been recorded@footnote{This requires a recent version of Guix, from May 2024 or more recent.}: @example guix git authenticate @end example When your configuration for your local Git repository doesn't match the default one, you can provide the reference for the @code{keyring} branch @i{via} the @option{-k} option. The following example assumes that you have a Git remote called @samp{myremote} pointing to the official repository: @example guix git authenticate \ -k myremote/keyring \ 9edb3f66fd807b096b48283debdcddccfea34bad \ "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA" @end example @xref{Invoking guix git authenticate}, for more information on this command. @quotation Note By default, hooks are installed such that @command{guix git authenticate} is invoked anytime you run @command{git pull} or @command{git push}. @end quotation After updating the repository, @command{make} might fail with an error similar to the following example: @example error: failed to load 'gnu/packages/linux.scm': ice-9/eval.scm:293:34: In procedure abi-check: #<record-type <origin>>: record ABI mismatch; recompilation needed @end example This means that one of the record types that Guix defines (in this example, the @code{origin} record) has changed, and all of guix needs to be recompiled to take that change into account. To do so, run @command{make clean-go} followed by @command{make}. Should @command{make} fail with an Automake error message after updating, you need to repeat the steps outlined in this section, commencing with @command{./bootstrap}. @node Running the Test Suite @section Running the Test Suite @cindex test suite After a successful @command{configure} and @code{make} run, it is a good idea to run the test suite. It can help catch issues with the setup or environment, or bugs in Guix itself---and really, reporting test failures is a good way to help improve the software. To run the test suite, type: @example make check @end example Test cases can run in parallel: you can use the @code{-j} option of GNU@tie{}make to speed things up. The first run may take a few minutes on a recent machine; subsequent runs will be faster because the store that is created for test purposes will already have various things in cache. It is also possible to run a subset of the tests by defining the @code{TESTS} makefile variable as in this example: @example make check TESTS="tests/store.scm tests/cpio.scm" @end example By default, tests results are displayed at a file level. In order to see the details of every individual test cases, it is possible to define the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example: @example make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" @end example The underlying SRFI 64 custom Automake test driver used for the 'check' test suite (located at @file{build-aux/test-driver.scm}) also allows selecting which test cases to run at a finer level, via its @option{--select} and @option{--exclude} options. Here's an example, to run all the test cases from the @file{tests/packages.scm} test file whose names start with ``transaction-upgrade-entry'': @example export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry" make check TESTS="tests/packages.scm" @end example Those wishing to inspect the results of failed tests directly from the command line can add the @option{--errors-only=yes} option to the @code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE} Automake makefile variable, as in: @example make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1 @end example The @option{--show-duration=yes} option can be used to print the duration of the individual test cases, when used in combination with @option{--brief=no}: @example make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes" @end example @xref{Parallel Test Harness,,,automake,GNU Automake} for more information about the Automake Parallel Test Harness. Upon failure, please email @email{bug-guix@@gnu.org} and attach the @file{test-suite.log} file. Please specify the Guix version being used as well as version numbers of the dependencies (@pxref{Requirements}) in your message. Guix also comes with a whole-system test suite that tests complete Guix System instances. It can only run on systems where Guix is already installed, using: @example make check-system @end example @noindent or, again, by defining @code{TESTS} to select a subset of tests to run: @example make check-system TESTS="basic mcron" @end example These system tests are defined in the @code{(gnu tests @dots{})} modules. They work by running the operating systems under test with lightweight instrumentation in a virtual machine (VM). They can be computationally intensive or rather cheap, depending on whether substitutes are available for their dependencies (@pxref{Substitutes}). Some of them require a lot of storage space to hold VM images. If you encounter an error like: @example Compiling Scheme modules... ice-9/eval.scm:142:16: In procedure compile-top-call: error: all-system-tests: unbound variable hint: Did you forget `(use-modules (gnu tests))'? @end example @noindent there may be inconsistencies in the work tree from previous builds. To resolve this, try running @command{make clean-go} followed by @command{make}. Again in case of test failures, please send @email{bug-guix@@gnu.org} all the details. @node Running Guix Before It Is Installed @section Running Guix Before It Is Installed In order to keep a sane working environment, you will find it useful to test the changes made in your local source tree checkout without actually installing them. So that you can distinguish between your ``end-user'' hat and your ``motley'' costume. To that end, all the command-line tools can be used even if you have not run @code{make install}. To do that, you first need to have an environment with all the dependencies available (@pxref{Building from Git}), and then simply prefix each command with @command{./pre-inst-env} (the @file{pre-inst-env} script lives in the top build tree of Guix; @pxref{Building from Git} to generate it). As an example, here is how you would build the @code{hello} package as defined in your working tree (this assumes @command{guix-daemon} is already running on your system; it's OK if it's a different version): @example $ ./pre-inst-env guix build hello @end example @noindent Similarly, an example for a Guile session using the Guix modules: @example $ ./pre-inst-env guile -c '(use-modules (guix utils)) (pk (%current-system))' ;;; ("x86_64-linux") @end example @noindent @cindex REPL @cindex read-eval-print loop @dots{} and for a REPL (@pxref{Using Guix Interactively}): @example $ ./pre-inst-env guile scheme@@(guile-user)> ,use(guix) scheme@@(guile-user)> ,use(gnu) scheme@@(guile-user)> (define snakes (fold-packages (lambda (package lst) (if (string-prefix? "python" (package-name package)) (cons package lst) lst)) '())) scheme@@(guile-user)> (length snakes) $1 = 361 @end example If you are hacking on the daemon and its supporting code or if @command{guix-daemon} is not already running on your system, you can launch it straight from the build tree@footnote{The @option{-E} flag to @command{sudo} guarantees that @code{GUILE_LOAD_PATH} is correctly set such that @command{guix-daemon} and the tools it uses can find the Guile modules they need.}: @example $ sudo -E ./pre-inst-env guix-daemon --build-users-group=guixbuild @end example The @command{pre-inst-env} script sets up all the environment variables necessary to support this, including @env{PATH} and @env{GUILE_LOAD_PATH}. Note that @command{./pre-inst-env guix pull} does @emph{not} upgrade the local source tree; it simply updates the @file{~/.config/guix/current} symlink (@pxref{Invoking guix pull}). Run @command{git pull} instead if you want to upgrade your local source tree. Sometimes, especially if you have recently updated your repository, running @command{./pre-inst-env} will print a message similar to the following example: @example ;;; note: source file /home/user/projects/guix/guix/progress.scm ;;; newer than compiled /home/user/projects/guix/guix/progress.go @end example This is only a note and you can safely ignore it. You can get rid of the message by running @command{make -j4}. Until you do, Guile will run slightly slower because it will interpret the code instead of using prepared Guile object (@file{.go}) files. You can run @command{make} automatically as you work using @command{watchexec} from the @code{watchexec} package. For example, to build again each time you update a package file, run @samp{watchexec -w gnu/packages -- make -j4}. @node The Perfect Setup @section The Perfect Setup The Perfect Setup to hack on Guix is basically the perfect setup used for Guile hacking (@pxref{Using Guile in Emacs,,, guile, Guile Reference Manual}). First, you need more than an editor, you need @url{https://www.gnu.org/software/emacs, Emacs}, empowered by the wonderful @url{https://nongnu.org/geiser/, Geiser}. To set that up, run: @example guix install emacs guile emacs-geiser emacs-geiser-guile @end example Geiser allows for interactive and incremental development from within Emacs: code compilation and evaluation from within buffers, access to on-line documentation (docstrings), context-sensitive completion, @kbd{M-.} to jump to an object definition, a REPL to try out your code, and more (@pxref{Introduction,,, geiser, Geiser User Manual}). If you allow Emacs to load the @file{.dir-locals.el} file at the root of the project checkout, it will cause Geiser to automatically add the local Guix sources to the Guile load path. To actually edit the code, Emacs already has a neat Scheme mode. But in addition to that, you must not miss @url{https://www.emacswiki.org/emacs/ParEdit, Paredit}. It provides facilities to directly operate on the syntax tree, such as raising an s-expression or wrapping it, swallowing or rejecting the following s-expression, etc. @cindex code snippets @cindex templates @cindex reducing boilerplate We also provide templates for common git commit messages and package definitions in the @file{etc/snippets} directory. These templates can be used to expand short trigger strings to interactive text snippets. If you use @url{https://joaotavora.github.io/yasnippet/, YASnippet}, you may want to add the @file{etc/snippets/yas} snippets directory to the @var{yas-snippet-dirs} variable. If you use @url{https://github.com/minad/tempel/, Tempel}, you may want to add the @file{etc/snippets/tempel/*} path to the @var{tempel-path} variable in Emacs. @lisp ;; @r{Assuming the Guix checkout is in ~/src/guix.} ;; @r{Yasnippet configuration} (with-eval-after-load 'yasnippet (add-to-list 'yas-snippet-dirs "~/src/guix/etc/snippets/yas")) ;; @r{Tempel configuration} (with-eval-after-load 'tempel ;; Ensure tempel-path is a list -- it may also be a string. (unless (listp 'tempel-path) (setq tempel-path (list tempel-path))) (add-to-list 'tempel-path "~/src/guix/etc/snippets/tempel/*")) @end lisp The commit message snippets depend on @url{https://magit.vc/, Magit} to display staged files. When editing a commit message type @code{add} followed by @kbd{TAB} to insert a commit message template for adding a package; type @code{update} followed by @kbd{TAB} to insert a template for updating a package; type @code{https} followed by @kbd{TAB} to insert a template for changing the home page URI of a package to HTTPS. The main snippet for @code{scheme-mode} is triggered by typing @code{package...} followed by @kbd{TAB}. This snippet also inserts the trigger string @code{origin...}, which can be expanded further. The @code{origin} snippet in turn may insert other trigger strings ending on @code{...}, which also can be expanded further. @cindex insert or update copyright @cindex @code{M-x guix-copyright} @cindex @code{M-x copyright-update} We additionally provide insertion and automatic update of a copyright in @file{etc/copyright.el}. You may want to set your full name, mail, and load a file. @lisp (setq user-full-name "Alice Doe") (setq user-mail-address "alice@@mail.org") ;; @r{Assuming the Guix checkout is in ~/src/guix.} (load-file "~/src/guix/etc/copyright.el") @end lisp To insert a copyright at the current line invoke @code{M-x guix-copyright}. To update a copyright you need to specify a @code{copyright-names-regexp}. @lisp (setq copyright-names-regexp (format "%s <%s>" user-full-name user-mail-address)) @end lisp You can check if your copyright is up to date by evaluating @code{M-x copyright-update}. If you want to do it automatically after each buffer save then add @code{(add-hook 'after-save-hook 'copyright-update)} in Emacs. @node Viewing Bugs within Emacs @subsection Viewing Bugs within Emacs Emacs has a nice minor mode called @code{bug-reference}, which, when combined with @samp{emacs-debbugs} (the Emacs package), can be used to open links such as @samp{<https://bugs.gnu.org/58697>} or @samp{<https://issues.guix.gnu.org/58697>} as bug report buffers. From there you can easily consult the email thread via the Gnus interface, reply or modify the bug status, all without leaving the comfort of Emacs! Below is a sample configuration to add to your @file{~/.emacs} configuration file: @lisp ;;; Bug references. (require 'bug-reference) (add-hook 'prog-mode-hook #'bug-reference-prog-mode) (add-hook 'gnus-mode-hook #'bug-reference-mode) (add-hook 'erc-mode-hook #'bug-reference-mode) (add-hook 'gnus-summary-mode-hook #'bug-reference-mode) (add-hook 'gnus-article-mode-hook #'bug-reference-mode) ;;; This extends the default expression (the top-most, first expression ;;; provided to 'or') to also match URLs such as ;;; <https://issues.guix.gnu.org/58697> or <https://bugs.gnu.org/58697>. ;;; It is also extended to detect "Fixes: #NNNNN" git trailers. (setq bug-reference-bug-regexp (rx (group (or (seq word-boundary (or (seq (char "Bb") "ug" (zero-or-one " ") (zero-or-one "#")) (seq (char "Pp") "atch" (zero-or-one " ") "#") (seq (char "Ff") "ixes" (zero-or-one ":") (zero-or-one " ") "#") (seq "RFE" (zero-or-one " ") "#") (seq "PR " (one-or-more (char "a-z+-")) "/")) (group (one-or-more (char "0-9")) (zero-or-one (seq "#" (one-or-more (char "0-9")))))) (seq (? "<") "https://bugs.gnu.org/" (group-n 2 (one-or-more (char "0-9"))) (? ">")) (seq (? "<") "https://issues.guix.gnu.org/" (? "issue/") (group-n 2 (one-or-more (char "0-9"))) (? ">")))))) (setq bug-reference-url-format "https://issues.guix.gnu.org/%s") (require 'debbugs) (require 'debbugs-browse) (add-hook 'bug-reference-mode-hook #'debbugs-browse-mode) (add-hook 'bug-reference-prog-mode-hook #'debbugs-browse-mode) ;; The following allows Emacs Debbugs user to open the issue directly within ;; Emacs. (setq debbugs-browse-url-regexp (rx line-start "http" (zero-or-one "s") "://" (or "debbugs" "issues.guix" "bugs") ".gnu.org" (one-or-more "/") (group (zero-or-one "cgi/bugreport.cgi?bug=")) (group-n 3 (one-or-more digit)) line-end)) ;; Change the default when run as 'M-x debbugs-gnu'. (setq debbugs-gnu-default-packages '("guix" "guix-patches")) ;; Show feature requests. (setq debbugs-gnu-default-severities '("serious" "important" "normal" "minor" "wishlist")) @end lisp For more information, refer to @ref{Bug Reference,,, emacs, The GNU Emacs Manual} and @ref{Minor Mode,,, debbugs-ug, The Debbugs User Guide}. @node Alternative Setups @section Alternative Setups Alternative setups than Emacs may let you work on Guix with a similar development experience and they might work better with the tools you currently use or help you make the transition to Emacs. The options listed below only provide the alternatives to the Emacs based setup, which is the most widely used in the Guix community. If you want to really understand how is the perfect setup for Guix development supposed to work, we encourage you to read the section before this regardless the editor you choose to use. @menu * Guile Studio:: First step in your transition to Emacs. * Vim and NeoVim:: When you are evil to the root. @end menu @node Guile Studio @subsection Guile Studio Guile Studio is a pre-configured Emacs with mostly everything you need to start hacking in Guile. If you are not familiar with Emacs it makes the transition easier for you. @example guix install guile-studio @end example Guile Studio comes with Geiser preinstalled and prepared for action. @node Vim and NeoVim @subsection Vim and NeoVim Vim (and NeoVim) are also packaged in Guix, just in case you decided to go for the evil path. @example guix install vim @end example If you want to enjoy a similar development experience to that in the perfect setup, you should install several plugins to configure the editor. Vim (and NeoVim) have the equivalent to Paredit, @uref{https://www.vim.org/scripts/script.php?script_id=3998, @code{paredit.vim}}, that will help you with the structural editing of Scheme files (the support for very large files is not great, though). @example guix install vim-paredit @end example We also recommend that you run @code{:set autoindent} so that your code is automatically indented as you type. For the interaction with Git, @uref{https://www.vim.org/scripts/script.php?script_id=2975, @code{fugitive.vim}} is the most commonly used plugin: @example guix install vim-fugitive @end example And of course if you want to interact with Guix directly from inside of vim, using the built-in terminal emulator, we have our very own @code{guix.vim} package! @example guix install vim-guix-vim @end example In NeoVim you can even make a similar setup to Geiser using @url{https://conjure.fun/, Conjure} that lets you connect to a running Guile process and inject your code there live (sadly it's not packaged in Guix yet). @node Source Tree Structure @section Source Tree Structure @cindex structure, of the source tree If you're willing to contribute to Guix beyond packages, or if you'd like to learn how it all fits together, this section provides a guided tour in the code base that you may find useful. Overall, the Guix source tree contains almost exclusively Guile @dfn{modules}, each of which can be seen as an independent library (@pxref{Modules,,, guile, GNU Guile Reference Manual}). The following table gives an overview of the main directories and what they contain. Remember that in Guile, each module name is derived from its file name---e.g., the module in file @file{guix/packages.scm} is called @code{(guix packages)}. @table @file @item guix This is the location of core Guix mechanisms. To illustrate what is meant by ``core'', here are a few examples, starting from low-level tools and going towards higher-level tools: @table @code @item (guix store) Connecting to and interacting with the build daemon (@pxref{The Store}). @item (guix derivations) Creating derivations (@pxref{Derivations}). @item (guix gexps) Writing G-expressions (@pxref{G-Expressions}). @item (guix packages) Defining packages and origins (@pxref{package Reference}). @item (guix download) @itemx (guix git-download) The @code{url-fetch} and @code{git-fetch} origin download methods (@pxref{origin Reference}). @item (guix swh) Fetching source code from the @uref{https://archive.softwareheritage.org,Software Heritage archive}. @item (guix search-paths) Implementing search paths (@pxref{Search Paths}). @item (guix build-system) The build system interface (@pxref{Build Systems}). @item (guix profiles) Implementing profiles. @end table @cindex build system, directory structure @item guix/build-system This directory contains specific build system implementations (@pxref{Build Systems}), such as: @table @code @item (guix build-system gnu) the GNU build system; @item (guix build-system cmake) the CMake build system; @item (guix build-system pyproject) The Python ``pyproject'' build system. @end table @item guix/build This contains code generally used on the ``build side'' (@pxref{G-Expressions, strata of code}). This includes code used to build packages or other operating system components, as well as utilities: @table @code @item (guix build utils) Utilities for package definitions and more (@pxref{Build Utilities}). @item (guix build gnu-build-system) @itemx (guix build cmake-build-system) @itemx (guix build pyproject-build-system) Implementation of build systems, and in particular definition of their build phases (@pxref{Build Phases}). @item (guix build syscalls) Interface to the C library and to Linux system calls. @end table @cindex command-line tools, as Guile modules @cindex command modules @item guix/scripts This contains modules corresponding to @command{guix} sub-commands. For example, the @code{(guix scripts shell)} module exports the @code{guix-shell} procedure, which directly corresponds to the @command{guix shell} command (@pxref{Invoking guix shell}). @cindex importer modules @item guix/import This contains supporting code for the importers and updaters (@pxref{Invoking guix import}, and @pxref{Invoking guix refresh}). For example, @code{(guix import pypi)} defines the interface to PyPI, which is used by the @code{guix import pypi} command. @end table The directories we have seen so far all live under @file{guix/}. The other important place is the @file{gnu/} directory, which contains primarily package definitions as well as libraries and tools for Guix System (@pxref{System Configuration}) and Guix Home (@pxref{Home Configuration}), all of which build upon functionality provided by @code{(guix @dots{})} modules@footnote{For this reason, @code{(guix @dots{})} modules must generally not depend on @code{(gnu @dots{})} modules, with notable exceptions: @code{(guix build-system @dots{})} modules may look up packages at run time---e.g., @code{(guix build-system cmake)} needs to access the @code{cmake} variable at run time---, @code{(guix scripts @dots{})} often rely on @code{(gnu @dots{})} modules, and the same goes for some of the @code{(guix import @dots{})} modules.}. @table @file @cindex package modules @item gnu/packages This is by far the most crowded directory of the source tree: it contains @dfn{package modules} that export package definitions (@pxref{Package Modules}). A few examples: @table @code @item (gnu packages base) Module providing ``base'' packages: @code{glibc}, @code{coreutils}, @code{grep}, etc. @item (gnu packages guile) Guile and core Guile packages. @item (gnu packages linux) The Linux-libre kernel and related packages. @item (gnu packages python) Python and core Python packages. @item (gnu packages python-xyz) Miscellaneous Python packages (we were not very creative). @end table In any case, you can jump to a package definition using @command{guix edit} (@pxref{Invoking guix edit}) and view its location with @command{guix show} (@pxref{Invoking guix package}). @findex search-patches @item gnu/packages/patches This directory contains patches applied against packages and obtained using the @code{search-patches} procedure. @item gnu/services This contains service definitions, primarily for Guix System (@pxref{Services}) but some of them are adapted and reused for Guix Home as we will see below. Examples: @table @code @item (gnu services) The service framework itself, which defines the service and service type data types (@pxref{Service Composition}). @item (gnu services base) ``Base'' services (@pxref{Base Services}). @item (gnu services desktop) ``Desktop'' services (@pxref{Desktop Services}). @item (gnu services shepherd) Support for Shepherd services (@pxref{Shepherd Services}). @end table You can jump to a service definition using @command{guix system edit} and view its location with @command{guix system search} (@pxref{Invoking guix system}). @item gnu/system These are core Guix System modules, such as: @table @code @item (gnu system) Defines @code{operating-system} (@pxref{operating-system Reference}). @item (gnu system file-systems) Defines @code{file-system} (@pxref{File Systems}). @item (gnu system mapped-devices) Defines @code{mapped-device} (@pxref{Mapped Devices}). @end table @item gnu/build These are modules that are either used on the ``build side'' when building operating systems or packages, or at run time by operating systems. @table @code @item (gnu build accounts) Creating @file{/etc/passwd}, @file{/etc/shadow}, etc. (@pxref{User Accounts}). @item (gnu build activation) Activating an operating system at boot time or reconfiguration time. @item (gnu build file-systems) Searching, checking, and mounting file systems. @item (gnu build linux-boot) @itemx (gnu build hurd-boot) Booting GNU/Linux and GNU/Hurd operating systems. @item (gnu build linux-initrd) Creating a Linux initial RAM disk (@pxref{Initial RAM Disk}). @end table @item gnu/home This contains all things Guix Home (@pxref{Home Configuration}); examples: @table @code @item (gnu home services) Core services such as @code{home-files-service-type}. @item (gnu home services ssh) SSH-related services (@pxref{Secure Shell}). @end table @item gnu/installer This contains the text-mode graphical system installer (@pxref{Guided Graphical Installation}). @item gnu/machine These are the @dfn{machine abstractions} used by @command{guix deploy} (@pxref{Invoking guix deploy}). @item gnu/tests This contains system tests---tests that spawn virtual machines to check that system services work as expected (@pxref{Running the Test Suite}). @end table Last, there's also a few directories that contain files that are @emph{not} Guile modules: @table @file @item nix This is the C++ implementation of @command{guix-daemon}, inherited from Nix (@pxref{Invoking guix-daemon}). @item tests These are unit tests, each file corresponding more or less to one module, in particular @code{(guix @dots{})} modules (@pxref{Running the Test Suite}). @item doc This is the documentation in the form of Texinfo files: this manual and the Cookbook. @xref{Writing a Texinfo File,,, texinfo, GNU Texinfo}, for information on Texinfo markup language. @item po This is the location of translations of Guix itself, of package synopses and descriptions, of the manual, and of the cookbook. Note that @file{.po} files that live here are pulled directly from Weblate (@pxref{Translating Guix}). @item etc Miscellaneous files: shell completions, support for systemd and other init systems, Git hooks, etc. @end table With all this, a fair chunk of your operating system is at your fingertips! Beyond @command{grep} and @command{git grep}, @pxref{The Perfect Setup} on how to navigate code from your editor, and @pxref{Using Guix Interactively} for information on how to use Scheme modules interactively. Enjoy! @node Packaging Guidelines @section Packaging Guidelines @cindex packages, creating The GNU distribution is nascent and may well lack some of your favorite packages. This section describes how you can help make the distribution grow. Free software packages are usually distributed in the form of @dfn{source code tarballs}---typically @file{tar.gz} files that contain all the source files. Adding a package to the distribution means essentially two things: adding a @dfn{recipe} that describes how to build the package, including a list of other packages required to build it, and adding @dfn{package metadata} along with that recipe, such as a description and licensing information. In Guix all this information is embodied in @dfn{package definitions}. Package definitions provide a high-level view of the package. They are written using the syntax of the Scheme programming language; in fact, for each package we define a variable bound to the package definition, and export that variable from a module (@pxref{Package Modules}). However, in-depth Scheme knowledge is @emph{not} a prerequisite for creating packages. For more information on package definitions, @pxref{Defining Packages}. Once a package definition is in place, stored in a file in the Guix source tree, it can be tested using the @command{guix build} command (@pxref{Invoking guix build}). For example, assuming the new package is called @code{gnew}, you may run this command from the Guix build tree (@pxref{Running Guix Before It Is Installed}): @example ./pre-inst-env guix build gnew --keep-failed @end example Using @code{--keep-failed} makes it easier to debug build failures since it provides access to the failed build tree. Another useful command-line option when debugging is @code{--log-file}, to access the build log. If the package is unknown to the @command{guix} command, it may be that the source file contains a syntax error, or lacks a @code{define-public} clause to export the package variable. To figure it out, you may load the module from Guile to get more information about the actual error: @example ./pre-inst-env guile -c '(use-modules (gnu packages gnew))' @end example Once your package builds correctly, please send us a patch (@pxref{Submitting Patches}). Well, if you need help, we will be happy to help you too. Once the patch is committed in the Guix repository, the new package auto