guix - Wojtek's customized Guix

diff options

Diffstat (limited to 'gnu/packages/check.scm')

0 files changed, 0 insertions, 0 deletions

e 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 Optionally, @code{--localstatedir} and @code{--sysconfdir} can also be provided as arguments. By default, @code{localstatedir} is @file{/var} (@pxref{The Store}, for information about this) and @code{sysconfdir} is @file{/etc}. 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 @command{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 automatically gets built on the supported platforms by @url{https://@value{SUBSTITUTE-SERVER-1}, our continuous integration system}. @cindex substituter Users can obtain the new package definition simply by running @command{guix pull} (@pxref{Invoking guix pull}). When @code{@value{SUBSTITUTE-SERVER-1}} is done building the package, installing the package automatically downloads binaries from there (@pxref{Substitutes}). The only place where human intervention is needed is to review and apply the patch. @menu * Software Freedom:: What may go into the distribution. * Package Naming:: What's in a name? * Version Numbers:: When the name is not enough. * Synopses and Descriptions:: Helping users find the right package. * Snippets versus Phases:: Whether to use a snippet, or a build phase. * Cyclic Module Dependencies:: Going full circle. * Emacs Packages:: Your Elisp fix. * Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. * Java Packages:: Coffee break. * Rust Crates:: Beware of oxidation. * Elm Packages:: Trees of browser code * Fonts:: Fond of fonts. @end menu @node Software Freedom @subsection Software Freedom @c Adapted from http://www.gnu.org/philosophy/philosophy.html. @cindex free software The GNU operating system has been developed so that users can have freedom in their computing. GNU is @dfn{free software}, meaning that users have the @url{https://www.gnu.org/philosophy/free-sw.html,four essential freedoms}: to run the program, to study and change the program in source code form, to redistribute exact copies, and to distribute modified versions. Packages found in the GNU distribution provide only software that conveys these four freedoms. In addition, the GNU distribution follow the @url{https://www.gnu.org/distros/free-system-distribution-guidelines.html,free software distribution guidelines}. Among other things, these guidelines reject non-free firmware, recommendations of non-free software, and discuss ways to deal with trademarks and patents. Some otherwise free upstream package sources contain a small and optional subset that violates the above guidelines, for instance because this subset is itself non-free code. When that happens, the offending items are removed with appropriate patches or code snippets in the @code{origin} form of the package (@pxref{Defining Packages}). This way, @code{guix build --source} returns the ``freed'' source rather than the unmodified upstream source. @node Package Naming @subsection Package Naming @cindex package name A package actually has two names associated with it. First, there is the name of the @emph{Scheme variable}, the one following @code{define-public}. By this name, the package can be made known in the Scheme code, for instance as input to another package. Second, there is the string in the @code{name} field of a package definition. This name is used by package management commands such as @command{guix package} and @command{guix build}. Both are usually the same and correspond to the lowercase conversion of the project name chosen upstream, with underscores replaced with hyphens. For instance, GNUnet is available as @code{gnunet}, and SDL_net as @code{sdl-net}. A noteworthy exception to this rule is when the project name is only a single character, or if an older maintained project with the same name already exists---regardless of whether it has already been packaged for Guix. Use common sense to make such names unambiguous and meaningful. For example, Guix's package for the shell called ``s'' upstream is @code{s-shell} and @emph{not} @code{s}. Feel free to ask your fellow hackers for inspiration. We do not add @code{lib} prefixes for library packages, unless these are already part of the official project name. But @pxref{Python Modules} and @ref{Perl Modules} for special rules concerning modules for the Python and Perl languages. Font package names are handled differently, @pxref{Fonts}. @node Version Numbers @subsection Version Numbers @cindex package version We usually package only the latest version of a given free software project. But sometimes, for instance for incompatible library versions, two (or more) versions of the same package are needed. These require different Scheme variable names. We use the name as defined in @ref{Package Naming} for the most recent version; previous versions use the same name, suffixed by @code{-} and the smallest prefix of the version number that may distinguish the two versions. The name inside the package definition is the same for all versions of a package and does not contain any version number. For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as follows: @lisp (define-public gtk+ (package (name "gtk+") (version "3.9.12") ...)) (define-public gtk+-2 (package (name "gtk+") (version "2.24.20") ...)) @end lisp If we also wanted GTK+ 3.8.2, this would be packaged as @lisp (define-public gtk+-3.8 (package (name "gtk+") (version "3.8.2") ...)) @end lisp @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>, @c for a discussion of what follows. @cindex version number, for VCS snapshots Occasionally, we package snapshots of upstream's version control system (VCS) instead of formal releases. This should remain exceptional, because it is up to upstream developers to clarify what the stable release is. Yet, it is sometimes necessary. So, what should we put in the @code{version} field? Clearly, we need to make the commit identifier of the VCS snapshot visible in the version string, but we also need to make sure that the version string is monotonically increasing so that @command{guix package --upgrade} can determine which version is newer. Since commit identifiers, notably with Git, are not monotonically increasing, we add a revision number that we increase each time we upgrade to a newer snapshot. The resulting version string looks like this: @example 2.0.11-3.cabba9e ^ ^ ^ | | `-- upstream commit ID | | | `--- Guix package revision | latest upstream version @end example It is a good idea to strip commit identifiers in the @code{version} field to, say, 7 digits. It avoids an aesthetic annoyance (assuming aesthetics have a role to play here) as well as problems related to OS limits such as the maximum shebang length (127 bytes for the Linux kernel). There are helper functions for doing this for packages using @code{git-fetch} or @code{hg-fetch} (see below). It is best to use the full commit identifiers in @code{origin}s, though, to avoid ambiguities. A typical package definition may look like this: @lisp (define my-package (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7") (revision "1")) ;Guix package revision (package (version (git-version "0.9" revision commit)) (source (origin (method git-fetch) (uri (git-reference (url "git://example.org/my-package.git") (commit commit))) (sha256 (base32 "1mbikn@dots{}")) (file-name (git-file-name name version)))) ;; @dots{} ))) @end lisp @deffn {Procedure} git-version @var{VERSION} @var{REVISION} @var{COMMIT} Return the version string for packages using @code{git-fetch}. @lisp (git-version "0.2.3" "0" "93818c936ee7e2f1ba1b315578bde363a7d43d05") @result{} "0.2.3-0.93818c9" @end lisp @end deffn @deffn {Procedure} hg-version @var{VERSION} @var{REVISION} @var{CHANGESET} Return the version string for packages using @code{hg-fetch}. It works in the same way as @code{git-version}. @end deffn @node Synopses and Descriptions @subsection Synopses and Descriptions @cindex package description @cindex package synopsis As we have seen before, each package in GNU@tie{}Guix includes a synopsis and a description (@pxref{Defining Packages}). Synopses and descriptions are important: They are what @command{guix package --search} searches, and a crucial piece of information to help users determine whether a given package suits their needs. Consequently, packagers should pay attention to what goes into them. Synopses must start with a capital letter and must not end with a period. They must not start with ``a'' or ``the'', which usually does not bring anything; for instance, prefer ``File-frobbing tool'' over ``A tool that frobs files''. The synopsis should say what the package is---e.g., ``Core GNU utilities (file, text, shell)''---or what it is used for---e.g., the synopsis for GNU@tie{}grep is ``Print lines matching a pattern''. Keep in mind that the synopsis must be meaningful for a very wide audience. For example, ``Manipulate alignments in the SAM format'' might make sense for a seasoned bioinformatics researcher, but might be fairly unhelpful or even misleading to a non-specialized audience. It is a good idea to come up with a synopsis that gives an idea of the application domain of the package. In this example, this might give something like ``Manipulate nucleotide sequence alignments'', which hopefully gives the user a better idea of whether this is what they are looking for. Descriptions should take between five and ten lines. Use full sentences, and avoid using acronyms without first introducing them. Please avoid marketing phrases such as ``world-leading'', ``industrial-strength'', and ``next-generation'', and avoid superlatives like ``the most advanced''---they are not helpful to users looking for a package and may even sound suspicious. Instead, try to be factual, mentioning use cases and features. @cindex Texinfo markup, in package descriptions Descriptions can include Texinfo markup, which is useful to introduce ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks (@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful when using some characters for example @samp{@@} and curly braces which are the basic special characters in Texinfo (@pxref{Special Characters,,, texinfo, GNU Texinfo}). User interfaces such as @command{guix show} take care of rendering it appropriately. Synopses and descriptions are translated by volunteers @uref{https://translate.fedoraproject.org/projects/guix/packages, at Weblate} so that as many users as possible can read them in their native language. User interfaces search them and display them in the language specified by the current locale. To allow @command{xgettext} to extract them as translatable strings, synopses and descriptions @emph{must be literal strings}. This means that you cannot use @code{string-append} or @code{format} to construct these strings: @lisp (package ;; @dots{} (synopsis "This is translatable") (description (string-append "This is " "*not*" " translatable."))) @end lisp Translation is a lot of work so, as a packager, please pay even more attention to your synopses and descriptions as every change may entail additional work for translators. In order to help them, it is possible to make recommendations or instructions visible to them by inserting special comments like this (@pxref{xgettext Invocation,,, gettext, GNU Gettext}): @lisp ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated. (description "ARandR is designed to provide a simple visual front end for the X11 resize-and-rotate (RandR) extension. @dots{}") @end lisp @node Snippets versus Phases @subsection Snippets versus Phases @cindex snippets, when to use The boundary between using an origin snippet versus a build phase to modify the sources of a package can be elusive. Origin snippets are typically used to remove unwanted files such as bundled libraries, nonfree sources, or to apply simple substitutions. The source derived from an origin should produce a source that can be used to build the package on any system that the upstream package supports (i.e., act as the corresponding source). In particular, origin snippets must not embed store items in the sources; such patching should rather be done using build phases. Refer to the @code{origin} record documentation for more information (@pxref{origin Reference}). @node Cyclic Module Dependencies @subsection Cyclic Module Dependencies While there cannot be circular dependencies between packages, Guile's lax module loading mechanism allows circular dependencies between Guile modules, which doesn't cause problems as long as the following conditions are followed for two modules part of a dependency cycle: @cindex rules to cope with circular module dependencies @enumerate @item Macros are not shared between the co-dependent modules @item Top-level variables are only referenced in delayed (@i{thunked}) package fields: @code{arguments}, @code{native-inputs}, @code{inputs}, @code{propagated-inputs} or @code{replacement} @item Procedures referencing top-level variables from another module are not called at the top level of a module themselves. @end enumerate Straying away from the above rules may work while there are no dependency cycles between modules, but given such cycles are confusing and difficult to troubleshoot, it is best to follow the rules to avoid introducing problems down the line. @noindent Here is a common trap to avoid: @lisp (define-public avr-binutils (package (inherit (cross-binutils "avr")) (name "avr-binutils"))) @end lisp In the above example, the @code{avr-binutils} package was defined in the module @code{(gnu packages avr)}, and the @code{cross-binutils} procedure in @code{(gnu packages cross-base)}. Because the @code{inherit} field is not delayed (thunked), it is evaluated at the top level at load time, which is problematic in the presence of module dependency cycles. This could be resolved by turning the package into a procedure instead, like: @lisp (define (make-avr-binutils) (package (inherit (cross-binutils "avr")) (name "avr-binutils"))) @end lisp Care would need to be taken to ensure the above procedure is only ever used in a package delayed fields or within another procedure also not called at the top level. @node Emacs Packages @subsection Emacs Packages @cindex emacs, packaging @cindex elisp, packaging Emacs packages should preferably use the Emacs build system (@pxref{emacs-build-system}), for uniformity and the benefits provided by its build phases, such as the auto-generation of the autoloads file and the byte compilation of the sources. Because there is no standardized way to run a test suite for Emacs packages, tests are disabled by default. When a test suite is available, it should be enabled by setting the @code{#:tests?} argument to @code{#true}. By default, the command to run the test is @command{make check}, but any command can be specified via the @code{#:test-command} argument. The @code{#:test-command} argument expects a list containing a command and its arguments, to be invoked during the @code{check} phase. The Elisp dependencies of Emacs packages are typically provided as @code{propagated-inputs} when required at run time. As for other packages, build or test dependencies should be specified as @code{native-inputs}. Emacs packages sometimes depend on resources directories that should be installed along the Elisp files. The @code{#:include} argument can be used for that purpose, by specifying a list of regexps to match. The best practice when using the @code{#:include} argument is to extend rather than override its default value (accessible via the @code{%default-include} variable). As an example, a yasnippet extension package typically include a @file{snippets} directory, which could be copied to the installation directory using: @lisp #:include (cons "^snippets/" %default-include) @end lisp When encountering problems, it is wise to check for the presence of the @code{Package-Requires} extension header in the package main source file, and whether any dependencies and their versions listed therein are satisfied. @node Python Modules @subsection Python Modules @cindex python We currently package Python 2 and Python 3, under the Scheme variable names @code{python-2} and @code{python} as explained in @ref{Version Numbers}. To avoid confusion and naming clashes with other programming languages, it seems desirable that the name of a package for a Python module contains the word @code{python}. Some modules are compatible with only one version of Python, others with both. If the package Foo is compiled with Python 3, we name it @code{python-foo}. If it is compiled with Python 2, we name it @code{python2-foo}. Python 2 packages are being removed from the distribution; please do no not submit any new Python 2 packages. If a project already contains the word @code{python}, we drop this; for instance, the module python-dateutil is packaged under the names @code{python-dateutil} and @code{python2-dateutil}. If the project name starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as described above. @quotation Note Currently there are two different build systems for Python packages in Guix: @var{python-build-system} and @var{pyproject-build-system}. For the longest time, Python packages were built from an informally specified @file{setup.py} file. That worked amazingly well, considering Python's success, but was difficult to build tooling around. As a result, a host of alternative build systems emerged and the community eventually settled on a @url{https://peps.python.org/pep-0517/, formal standard} for specifying build requirements. @var{pyproject-build-system} is Guix's implementation of this standard. It is considered ``experimental'' in that it does not yet support all the various PEP-517 @emph{build backends}, but you are encouraged to try it for new Python packages and report any problems. It will eventually be deprecated and merged into @var{python-build-system}. @end quotation @subsubsection Specifying Dependencies @cindex inputs, for Python packages Dependency information for Python packages is usually available in the package source tree, with varying degrees of accuracy: in the @file{pyproject.toml} file, the @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini} (the latter mostly for test dependencies). Your mission, when writing a recipe for a Python package, is to map these dependencies to the appropriate type of ``input'' (@pxref{package Reference, inputs}). Although the @code{pypi} importer normally does a good job (@pxref{Invoking guix import}), you may want to check the following check list to determine which dependency goes where. @itemize @item We currently package Python with @code{setuptools} and @code{pip} installed per default. This is about to change, and users are encouraged to use @code{python-toolchain} if they want a build environment for Python. @command{guix lint} will warn if @code{setuptools} or @code{pip} are added as native-inputs because they are generally not necessary. @item Python dependencies required at run time go into @code{propagated-inputs}. They are typically defined with the @code{install_requires} keyword in @file{setup.py}, or in the @file{requirements.txt} file. @item Python packages required only at build time---e.g., those listed under @code{build-system.requires} in @file{pyproject.toml} or with the @code{setup_requires} keyword in @file{setup.py}---or dependencies only for testing---e.g., those in @code{tests_require} or @file{tox.ini}---go into @code{native-inputs}. The rationale is that (1) they do not need to be propagated because they are not needed at run time, and (2) in a cross-compilation context, it's the ``native'' input that we'd want. Examples are the @code{pytest}, @code{mock}, and @code{nose} test frameworks. Of course if any of these packages is also required at run-time, it needs to go to @code{propagated-inputs}. @item Anything that does not fall in the previous categories goes to @code{inputs}, for example programs or C libraries required for building Python packages containing C extensions. @item If a Python package has optional dependencies (@code{extras_require}), it is up to you to decide whether to add them or not, based on their usefulness/overhead ratio (@pxref{Submitting Patches, @command{guix size}}). @end itemize @node Perl Modules @subsection Perl Modules @cindex perl Perl programs standing for themselves are named as any other package, using the lowercase upstream name. For Perl packages containing a single class, we use the lowercase class name, replace all occurrences of @code{::} by dashes and prepend the prefix @code{perl-}. So the class @code{XML::Parser} becomes @code{perl-xml-parser}. Modules containing several classes keep their lowercase upstream name and are also prepended by @code{perl-}. Such modules tend to have the word @code{perl} somewhere in their name, which gets dropped in favor of the prefix. For instance, @code{libwww-perl} becomes @code{perl-libwww}. @node Java Packages @subsection Java Packages @cindex java Java programs standing for themselves are named as any other package, using the lowercase upstream name. To avoid confusion and naming clashes with other programming languages, it is desirable that the name of a package for a Java package is prefixed with @code{java-}. If a project already contains the word @code{java}, we drop this; for instance, the package @code{ngsjava} is packaged under the name @code{java-ngs}. For Java packages containing a single class or a small class hierarchy, we use the lowercase class name, replace all occurrences of @code{.} by dashes and prepend the prefix @code{java-}. So the class @code{apache.commons.cli} becomes package @code{java-apache-commons-cli}. @node Rust Crates @subsection Rust Crates @cindex rust Rust programs standing for themselves are named as any other package, using the lowercase upstream name. To prevent namespace collisions we prefix all other Rust packages with the @code{rust-} prefix. The name should be changed to lowercase as appropriate and dashes should remain in place. In the rust ecosystem it is common for multiple incompatible versions of a package to be used at any given time, so all package definitions should have a versioned suffix. The versioned suffix is the left-most non-zero digit (and any leading zeros, of course). This follows the ``caret'' version scheme intended by Cargo. Examples@: @code{rust-clap-2}, @code{rust-rand-0.6}. Because of the difficulty in reusing rust packages as pre-compiled inputs for other packages the Cargo build system (@pxref{Build Systems, @code{cargo-build-system}}) presents the @code{#:cargo-inputs} and @code{cargo-development-inputs} keywords as build system arguments. It would be helpful to think of these as similar to @code{propagated-inputs} and @code{native-inputs}. Rust @code{dependencies} and @code{build-dependencies} should go in @code{#:cargo-inputs}, and @code{dev-dependencies} should go in @code{#:cargo-development-inputs}. If a Rust package links to other libraries then the standard placement in @code{inputs} and the like should be used. Care should be taken to ens


context:
space:
mode: