From a987d2c02525efd1bf37b4bb5b5df405a06bd15c Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Mon, 26 Aug 2013 22:11:04 +0200 Subject: derivations: Move 3 positional parameters into keyword parameters. * guix/derivations.scm (derivation): Turn `system', `env-vars', and `inputs' into keyword parameters. (build-expression->derivation): Adjust accordingly. * gnu/packages/bootstrap.scm (%bootstrap-guile): Likewise. * tests/derivations.scm, tests/store.scm: Likewise. * doc/guix.texi (Derivations): Likewise. --- doc/guix.texi | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index 57b6412939..c82d5f7480 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1113,7 +1113,7 @@ derivations as Scheme objects, along with procedures to create and otherwise manipulate derivations. The lowest-level primitive to create a derivation is the @code{derivation} procedure: -@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{system} @var{builder} @var{args} @var{env-vars} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] +@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] Build a derivation with the given arguments. Return the resulting store path and @code{} object. @@ -1137,9 +1137,9 @@ to a Bash executable in the store: (let ((builder ; add the Bash script to the store (add-text-to-store store "my-builder.sh" "echo hello world > $out\n" '()))) - (derivation store "foo" (%current-system) + (derivation store "foo" bash `("-e" ,builder) - '(("HOME" . "/homeless")) '()))) + #:env-vars '(("HOME" . "/homeless"))))) list) @result{} ("/nix/store/@dots{}-foo.drv" #< @dots{}>) @end lisp -- cgit v1.2.3 From 5b0c9d1635df1608a498db8718af575d2f0e1663 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Mon, 26 Aug 2013 22:12:46 +0200 Subject: derivations: Add #:dependency-graphs `derivation' parameter. * guix/derivations.scm (derivation): Add `dependency-graphs' keyword parameter; honor it. * tests/derivations.scm (bootstrap-binary): New procedure. (%bash): Use it. (%mkdir): New variable. (directory-contents): Add `slurp' optional parameter. ("derivation with #:dependency-graphs"): New test. * doc/guix.texi (Derivations): Update accordingly. --- doc/guix.texi | 7 +++++- guix/derivations.scm | 28 ++++++++++++++++++--- tests/derivations.scm | 68 +++++++++++++++++++++++++++++++++++++++++++++------ 3 files changed, 91 insertions(+), 12 deletions(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index c82d5f7480..86912ecabf 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1113,13 +1113,18 @@ derivations as Scheme objects, along with procedures to create and otherwise manipulate derivations. The lowest-level primitive to create a derivation is the @code{derivation} procedure: -@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] +@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] [#:dependency-graphs #f] Build a derivation with the given arguments. Return the resulting store path and @code{} object. When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a @dfn{fixed-output derivation} is created---i.e., one whose result is known in advance, such as a file download. + +When @var{dependency-graphs} is true, it must be a list of file +name/store path pairs. In that case, the reference graph of each store +path is exported in the build environment in the corresponding file, in +a simple text format. @end deffn @noindent diff --git a/guix/derivations.scm b/guix/derivations.scm index 3d7a30aaa8..fea9984370 100644 --- a/guix/derivations.scm +++ b/guix/derivations.scm @@ -501,11 +501,16 @@ the derivation called NAME with hash HASH." #:key (system (%current-system)) (env-vars '()) (inputs '()) (outputs '("out")) - hash hash-algo hash-mode) + hash hash-algo hash-mode + dependency-graphs) "Build a derivation with the given arguments. Return the resulting store path and object. When HASH, HASH-ALGO, and HASH-MODE are given, a fixed-output derivation is created---i.e., one whose result is -known in advance, such as a file download." +known in advance, such as a file download. + +When DEPENDENCY-GRAPHS is true, it must be a list of file name/store path +pairs. In that case, the reference graph of each store path is exported in +the build environment in the corresponding file, in a simple text format." (define direct-store-path? (let ((len (+ 1 (string-length (%store-prefix))))) (lambda (p) @@ -540,7 +545,22 @@ known in advance, such as a file download." value)))) env-vars)))))) - (define (env-vars-with-empty-outputs) + (define (user+system-env-vars) + ;; Some options are passed to the build daemon via the env. vars of + ;; derivations (urgh!). We hide that from our API, but here is the place + ;; where we kludgify those options. + (match dependency-graphs + (((file . path) ...) + (let ((value (map (cut string-append <> " " <>) + file path))) + ;; XXX: This all breaks down if an element of FILE or PATH contains + ;; white space. + `(("exportReferencesGraph" . ,(string-join value " ")) + ,@env-vars))) + (#f + env-vars))) + + (define (env-vars-with-empty-outputs env-vars) ;; Return a variant of ENV-VARS where each OUTPUTS is associated with an ;; empty string, even outputs that do not appear in ENV-VARS. (let ((e (map (match-lambda @@ -572,7 +592,7 @@ known in advance, such as a file download." #t "sha256" input))) (make-derivation-input path '())))) (delete-duplicates inputs))) - (env-vars (env-vars-with-empty-outputs)) + (env-vars (env-vars-with-empty-outputs (user+system-env-vars))) (drv-masked (make-derivation outputs (filter (compose derivation-path? derivation-input-path) diff --git a/tests/derivations.scm b/tests/derivations.scm index 9833e15112..9b3d92a7bf 100644 --- a/tests/derivations.scm +++ b/tests/derivations.scm @@ -50,19 +50,23 @@ (let ((drv (package-derivation %store %bootstrap-guile))) (%guile-for-build drv))) -(define %bash - (let ((bash (search-bootstrap-binary "bash" (%current-system)))) +(define (bootstrap-binary name) + (let ((bin (search-bootstrap-binary name (%current-system)))) (and %store - (add-to-store %store "bash" #t "sha256" bash)))) + (add-to-store %store name #t "sha256" bin)))) + +(define %bash + (bootstrap-binary "bash")) +(define %mkdir + (bootstrap-binary "mkdir")) -(define (directory-contents dir) +(define* (directory-contents dir #:optional (slurp get-bytevector-all)) "Return an alist representing the contents of DIR." (define prefix-len (string-length dir)) (sort (file-system-fold (const #t) ; enter? (lambda (path stat result) ; leaf (alist-cons (string-drop path prefix-len) - (call-with-input-file path - get-bytevector-all) + (call-with-input-file path slurp) result)) (lambda (path stat result) result) ; down (lambda (path stat result) result) ; up @@ -84,7 +88,7 @@ (and (equal? b1 b2) (equal? d1 d2)))) -(test-skip (if %store 0 11)) +(test-skip (if %store 0 12)) (test-assert "add-to-store, flat" (let* ((file (search-path %load-path "language/tree-il/spec.scm")) @@ -292,6 +296,56 @@ (and (valid-path? %store p) (equal? '(one two) (call-with-input-file p read))))))) +(test-assert "derivation with #:dependency-graphs" + (let* ((input1 (add-text-to-store %store "foo" "hello" + (list %bash))) + (input2 (add-text-to-store %store "bar" + (number->string (random 7777)) + (list input1))) + (builder (add-text-to-store %store "build-graph" + (format #f " +~a $out + (while read l ; do echo $l ; done) < bash > $out/bash + (while read l ; do echo $l ; done) < input1 > $out/input1 + (while read l ; do echo $l ; done) < input2 > $out/input2" + %mkdir) + (list %mkdir))) + (drv (derivation %store "closure-graphs" + %bash `(,builder) + #:dependency-graphs + `(("bash" . ,%bash) + ("input1" . ,input1) + ("input2" . ,input2)) + #:inputs `((,%bash) (,builder)))) + (out (derivation-path->output-path drv))) + (define (deps path . deps) + (let ((count (length deps))) + (string-append path "\n\n" (number->string count) "\n" + (string-join (sort deps string? input1 %bash) + (string-append (deps %bash) + (deps input1 %bash)) + (string-append (deps input1 %bash) + (deps %bash)))) + ("/input2" . ,(string-concatenate + (map cdr + (sort + (map (lambda (p d) + (cons p (apply deps p d))) + (list %bash input1 input2) + (list '() (list %bash) (list input1))) + (lambda (x y) + (match x + ((p1 . _) + (match y + ((p2 . _) + (string Date: Mon, 26 Aug 2013 22:19:21 +0200 Subject: derivations: Add #:dependency-graphs to `build-expression->derivation'. * guix/derivations.scm (build-expression->derivation): Add #:dependency-graphs keyword argument. Pass it to `derivation'. * tests/derivations.scm ("build-expression->derivation with #:dependency-graphs"): New test. * doc/guix.texi (Derivations): Update `build-expression->derivation' description. --- doc/guix.texi | 4 +++- guix/derivations.scm | 10 +++++++--- tests/derivations.scm | 34 +++++++++++++++++++++++++++++++++- 3 files changed, 43 insertions(+), 5 deletions(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index 86912ecabf..8c7af49922 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1153,7 +1153,7 @@ As can be guessed, this primitive is cumbersome to use directly. An improved variant is @code{build-expression->derivation}, which allows the caller to directly pass a Guile expression as the build script: -@deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:guile-for-build #f] +@deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:dependency-graphs #f] [#:guile-for-build #f] Return a derivation that executes Scheme expression @var{exp} as a builder for derivation @var{name}. @var{inputs} must be a list of @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted, @@ -1174,6 +1174,8 @@ terminates by passing the result of @var{exp} to @code{exit}; thus, when @var{exp} is built using @var{guile-for-build} (a derivation). When @var{guile-for-build} is omitted or is @code{#f}, the value of the @code{%guile-for-build} fluid is used instead. + +See the @code{derivation} procedure for the meaning of @var{dependency-graphs}. @end deffn @noindent diff --git a/guix/derivations.scm b/guix/derivations.scm index fea9984370..56a5466d9d 100644 --- a/guix/derivations.scm +++ b/guix/derivations.scm @@ -743,7 +743,8 @@ they can refer to each other." hash hash-algo (env-vars '()) (modules '()) - guile-for-build) + guile-for-build + dependency-graphs) "Return a derivation that executes Scheme expression EXP as a builder for derivation NAME. INPUTS must be a list of (NAME DRV-PATH SUB-DRV) tuples; when SUB-DRV is omitted, \"out\" is assumed. MODULES is a list @@ -760,7 +761,9 @@ builder terminates by passing the result of EXP to `exit'; thus, when EXP returns #f, the build is considered to have failed. EXP is built using GUILE-FOR-BUILD (a derivation). When GUILE-FOR-BUILD is -omitted or is #f, the value of the `%guile-for-build' fluid is used instead." +omitted or is #f, the value of the `%guile-for-build' fluid is used instead. + +See the `derivation' procedure for the meaning of DEPENDENCY-GRAPHS." (define guile-drv (or guile-for-build (%guile-for-build))) @@ -877,4 +880,5 @@ omitted or is #f, the value of the `%guile-for-build' fluid is used instead." env-vars) #:hash hash #:hash-algo hash-algo - #:outputs outputs))) + #:outputs outputs + #:dependency-graphs dependency-graphs))) diff --git a/tests/derivations.scm b/tests/derivations.scm index 9b3d92a7bf..f9e6c28ec8 100644 --- a/tests/derivations.scm +++ b/tests/derivations.scm @@ -376,7 +376,7 @@ (and (valid-path? %store p) (file-exists? (string-append p "/good"))))))) -(test-skip (if (%guile-for-build) 0 7)) +(test-skip (if (%guile-for-build) 0 8)) (test-assert "build-expression->derivation and derivation-prerequisites" (let-values (((drv-path drv) @@ -652,6 +652,38 @@ Deriver: ~a~%" (derivation-path->output-path final2)) (build-derivations %store (list final1 final2))))) +(test-assert "build-expression->derivation with #:dependency-graphs" + (let* ((input (add-text-to-store %store "foo" "hello" + (list %bash %mkdir))) + (builder '(copy-file "input" %output)) + (drv (build-expression->derivation %store "dependency-graphs" + (%current-system) + builder '() + #:dependency-graphs + `(("input" . ,input)))) + (out (derivation-path->output-path drv))) + (define (deps path . deps) + (let ((count (length deps))) + (string-append path "\n\n" (number->string count) "\n" + (string-join (sort deps string Date: Tue, 27 Aug 2013 18:34:49 +0200 Subject: derivations: Rename #:dependency-graphs to #:references-graphs. * guix/derivations.scm (derivation, build-expression->derivation): Rename #:dependency-graphs to #:references-graphs, for consistency in the terminology. * tests/derivations.scm: Adjust accordingly. --- doc/guix.texi | 8 ++++---- guix/derivations.scm | 12 ++++++------ tests/derivations.scm | 10 +++++----- 3 files changed, 15 insertions(+), 15 deletions(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index 8c7af49922..cda645f195 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1113,7 +1113,7 @@ derivations as Scheme objects, along with procedures to create and otherwise manipulate derivations. The lowest-level primitive to create a derivation is the @code{derivation} procedure: -@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] [#:dependency-graphs #f] +@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:hash-mode #f] [#:inputs '()] [#:env-vars '()] [#:system (%current-system)] [#:references-graphs #f] Build a derivation with the given arguments. Return the resulting store path and @code{} object. @@ -1121,7 +1121,7 @@ When @var{hash}, @var{hash-algo}, and @var{hash-mode} are given, a @dfn{fixed-output derivation} is created---i.e., one whose result is known in advance, such as a file download. -When @var{dependency-graphs} is true, it must be a list of file +When @var{references-graphs} is true, it must be a list of file name/store path pairs. In that case, the reference graph of each store path is exported in the build environment in the corresponding file, in a simple text format. @@ -1153,7 +1153,7 @@ As can be guessed, this primitive is cumbersome to use directly. An improved variant is @code{build-expression->derivation}, which allows the caller to directly pass a Guile expression as the build script: -@deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:dependency-graphs #f] [#:guile-for-build #f] +@deffn {Scheme Procedure} build-expression->derivation @var{store} @var{name} @var{system} @var{exp} @var{inputs} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] [#:env-vars '()] [#:modules '()] [#:references-graphs #f] [#:guile-for-build #f] Return a derivation that executes Scheme expression @var{exp} as a builder for derivation @var{name}. @var{inputs} must be a list of @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted, @@ -1175,7 +1175,7 @@ terminates by passing the result of @var{exp} to @code{exit}; thus, when @var{guile-for-build} is omitted or is @code{#f}, the value of the @code{%guile-for-build} fluid is used instead. -See the @code{derivation} procedure for the meaning of @var{dependency-graphs}. +See the @code{derivation} procedure for the meaning of @var{references-graphs}. @end deffn @noindent diff --git a/guix/derivations.scm b/guix/derivations.scm index 56a5466d9d..59a3957149 100644 --- a/guix/derivations.scm +++ b/guix/derivations.scm @@ -502,13 +502,13 @@ the derivation called NAME with hash HASH." (system (%current-system)) (env-vars '()) (inputs '()) (outputs '("out")) hash hash-algo hash-mode - dependency-graphs) + references-graphs) "Build a derivation with the given arguments. Return the resulting store path and object. When HASH, HASH-ALGO, and HASH-MODE are given, a fixed-output derivation is created---i.e., one whose result is known in advance, such as a file download. -When DEPENDENCY-GRAPHS is true, it must be a list of file name/store path +When REFERENCES-GRAPHS is true, it must be a list of file name/store path pairs. In that case, the reference graph of each store path is exported in the build environment in the corresponding file, in a simple text format." (define direct-store-path? @@ -549,7 +549,7 @@ the build environment in the corresponding file, in a simple text format." ;; Some options are passed to the build daemon via the env. vars of ;; derivations (urgh!). We hide that from our API, but here is the place ;; where we kludgify those options. - (match dependency-graphs + (match references-graphs (((file . path) ...) (let ((value (map (cut string-append <> " " <>) file path))) @@ -744,7 +744,7 @@ they can refer to each other." (env-vars '()) (modules '()) guile-for-build - dependency-graphs) + references-graphs) "Return a derivation that executes Scheme expression EXP as a builder for derivation NAME. INPUTS must be a list of (NAME DRV-PATH SUB-DRV) tuples; when SUB-DRV is omitted, \"out\" is assumed. MODULES is a list @@ -763,7 +763,7 @@ EXP returns #f, the build is considered to have failed. EXP is built using GUILE-FOR-BUILD (a derivation). When GUILE-FOR-BUILD is omitted or is #f, the value of the `%guile-for-build' fluid is used instead. -See the `derivation' procedure for the meaning of DEPENDENCY-GRAPHS." +See the `derivation' procedure for the meaning of REFERENCES-GRAPHS." (define guile-drv (or guile-for-build (%guile-for-build))) @@ -881,4 +881,4 @@ See the `derivation' procedure for the meaning of DEPENDENCY-GRAPHS." #:hash hash #:hash-algo hash-algo #:outputs outputs - #:dependency-graphs dependency-graphs))) + #:references-graphs references-graphs))) diff --git a/tests/derivations.scm b/tests/derivations.scm index f9e6c28ec8..9092e3acd6 100644 --- a/tests/derivations.scm +++ b/tests/derivations.scm @@ -296,7 +296,7 @@ (and (valid-path? %store p) (equal? '(one two) (call-with-input-file p read))))))) -(test-assert "derivation with #:dependency-graphs" +(test-assert "derivation with #:references-graphs" (let* ((input1 (add-text-to-store %store "foo" "hello" (list %bash))) (input2 (add-text-to-store %store "bar" @@ -312,7 +312,7 @@ (list %mkdir))) (drv (derivation %store "closure-graphs" %bash `(,builder) - #:dependency-graphs + #:references-graphs `(("bash" . ,%bash) ("input1" . ,input1) ("input2" . ,input2)) @@ -652,14 +652,14 @@ Deriver: ~a~%" (derivation-path->output-path final2)) (build-derivations %store (list final1 final2))))) -(test-assert "build-expression->derivation with #:dependency-graphs" +(test-assert "build-expression->derivation with #:references-graphs" (let* ((input (add-text-to-store %store "foo" "hello" (list %bash %mkdir))) (builder '(copy-file "input" %output)) - (drv (build-expression->derivation %store "dependency-graphs" + (drv (build-expression->derivation %store "references-graphs" (%current-system) builder '() - #:dependency-graphs + #:references-graphs `(("input" . ,input)))) (out (derivation-path->output-path drv))) (define (deps path . deps) -- cgit v1.2.3 From da7cabd46b20708d083329bd7ec9fd36bf218895 Mon Sep 17 00:00:00 2001 From: Andreas Enge Date: Wed, 28 Aug 2013 22:04:52 +0200 Subject: doc: Shuffle some text around. * doc/guix.texi: Drop duplicate copyright notice, start section "Packaging Guidelines" with existant text. --- doc/guix.texi | 75 ++++++++++++++++++++++++----------------------------------- 1 file changed, 31 insertions(+), 44 deletions(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index cda645f195..dfffdbf783 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -23,6 +23,7 @@ @title GNU Guix Reference Manual @subtitle Using the GNU Guix Functional Package Manager @author Ludovic Courtès +@author Andreas Enge @author Nikita Karetnikov @page @@ -30,7 +31,7 @@ Edition @value{EDITION} @* @value{UPDATED} @* -Copyright @copyright{} @value{YEARS} Ludovic Court@`es +Copyright @copyright{} @value{YEARS} Ludovic Court@`es, Andreas Enge, Nikita Karetnikov @quotation Permission is granted to copy, distribute and/or modify this document @@ -64,17 +65,6 @@ Documentation License.'' This document describes GNU Guix version @value{VERSION}, a functional package management tool written for the GNU system. -@quotation -Copyright @copyright{} @value{YEARS} Ludovic Courtès - -Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A -copy of the license is included in the section entitled ``GNU Free -Documentation License.'' -@end quotation - @menu * Introduction:: What is Guix about? * Installation:: Installing Guix. @@ -1502,7 +1492,7 @@ tools that help users exert that freedom. @menu * Installing Debugging Files:: Feeding the debugger. * Package Modules:: Packages from the programmer's viewpoint. -* Adding New Packages:: Growing the distribution. +* Packaging Guidelines:: Growing the distribution. * Bootstrapping:: GNU/Linux built from scratch. * Porting:: Targeting another platform or kernel. @end menu @@ -1587,41 +1577,14 @@ distribution. The root of this dependency graph is a small set of bootstrap)} module. For more information on bootstrapping, @ref{Bootstrapping}. -@node Adding New Packages -@section Adding New Packages +@node Packaging Guidelines +@section Packaging Guidelines 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. @ref{Contributing}, for additional information on how you can help. -@menu -* Packaging Guidelines:: What goes into the distribution. -* From the Source Tarball to the Package:: The story of a package. -@end menu - -@node Packaging Guidelines -@subsection Packaging Guidelines - -@c Adapted from http://www.gnu.org/philosophy/philosophy.html. - -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{http://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{http://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. - -@node From the Source Tarball to the Package -@subsection From the Source Tarball, to the Package Definition, to the Binary Package - 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 @@ -1667,6 +1630,30 @@ package automatically downloads binaries from there (except when using needed is to review and apply the patch. +@menu +* Software Freedom:: What may go into the distribution. +@end menu + +@node Software Freedom +@subsection Software Freedom + +@c Adapted from http://www.gnu.org/philosophy/philosophy.html. + +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{http://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{http://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. + + @node Bootstrapping @section Bootstrapping @@ -1836,8 +1823,8 @@ reason. 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}. We welcome ideas, bug reports, patches, and anything that may be helpful to -the project. We particularly welcome help on packaging (@pxref{Adding -New Packages}). +the project. We particularly welcome help on packaging +(@pxref{Packaging Guidelines}). Please see the @url{http://git.savannah.gnu.org/cgit/guix.git/tree/HACKING, -- cgit v1.2.3 From ee85f3dbe9ec38abffd08971be27b876634392ee Mon Sep 17 00:00:00 2001 From: Andreas Enge Date: Wed, 28 Aug 2013 22:51:20 +0200 Subject: doc: Add package guidelines for names and numbers. * doc/guix.texi: Three new subsections. --- doc/guix.texi | 82 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 81 insertions(+), 1 deletion(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index dfffdbf783..ca2871bc53 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1631,7 +1631,10 @@ needed is to review and apply the patch. @menu -* Software Freedom:: What may go into the distribution. +* Software Freedom:: What may go into the distribution. +* Package Naming:: What's in a name? +* Version Numbers:: When the name is not enough. +* Python Modules:: Taming the snake. @end menu @node Software Freedom @@ -1654,6 +1657,83 @@ reject non-free firmware, recommendations of non-free software, and discuss ways to deal with trademarks and patents. +@node Package Naming +@subsection Package Naming + +A package has actually two names associated to 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 the package manager. + +Both are usually the same and correspond to the lowercase conversion of the +project name chosen by upstream. For instance, the GNUnet project is packaged +as @code{gnunet}. We do not add @code{lib} prefixes for library packages, +unless these are already part of the official project name. +But see @ref{Python Modules} for special rules concerning modules for +the Python language. + + +@node Version Numbers +@subsection Version Numbers + +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: +@example +(define-public gtk+ + (package + (name "gtk+") + (version "3.9.12") + ...)) +(define-public gtk+-2 + (package + (name "gtk+") + (version "2.24.20") + ...)) +@end example +If we also wanted GTK+ 3.8.2, this would be packaged as +@example +(define-public gtk+-3.8 + (package + (name "gtk+") + (version "3.8.2") + ...)) +@end example + + +@node Python Modules +@subsection Python Modules + +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 compiles only with Python 3, we name it +@code{python-foo}; if it compiles only with Python 2, we name it +@code{python2-foo}. If it is compatible with both versions, we create two +packages with the corresponding names. + +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}. + + + + + @node Bootstrapping @section Bootstrapping -- cgit v1.2.3 From 29f66ddd7b0ef2da6356071da216b5dc92597301 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Thu, 29 Aug 2013 21:58:15 +0200 Subject: doc: Fix the image size in PDF/PS/DVI output. * doc/guix.texi (Bootstrapping): Specify an image width for the TeX output. Before that, the image would be much wider than the US Letter page width. --- doc/guix.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index ca2871bc53..6da3366dec 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1768,7 +1768,7 @@ re-create them if needed (more on that later.) @c As of Emacs 24.3, Info-mode displays the image, but since it's a @c large image, it's hard to scroll. Oh well. -@image{images/bootstrap-graph,,,Dependency graph of the early bootstrap derivations} +@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations} The figure above shows the very beginning of the dependency graph of the distribution, corresponding to the package definitions of the @code{(gnu -- cgit v1.2.3 From 46cb9da28597039a7d158ce4b8e0bcacf7700fe3 Mon Sep 17 00:00:00 2001 From: Andreas Enge Date: Thu, 29 Aug 2013 22:36:23 +0200 Subject: doc: Add duplicate copyright notice again. * doc/guix.texi: Add second copyright notice again inside @ifinfo, needed since the first one does not appear in the info output. Partially undoes commit da7cabd. --- doc/guix.texi | 15 +++++++++++++++ 1 file changed, 15 insertions(+) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index 6da3366dec..346685040a 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -33,6 +33,7 @@ Edition @value{EDITION} @* Copyright @copyright{} @value{YEARS} Ludovic Court@`es, Andreas Enge, Nikita Karetnikov +@ifinfo @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -41,6 +42,8 @@ Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''. @end quotation +@end ifinfo + @end titlepage @copying @@ -65,6 +68,18 @@ Documentation License.'' This document describes GNU Guix version @value{VERSION}, a functional package management tool written for the GNU system. + +@quotation +Copyright @copyright{} @value{YEARS} Ludovic Courtès, Andreas Enge, Nikita Karetnikov + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A +copy of the license is included in the section entitled ``GNU Free +Documentation License.'' +@end quotation + @menu * Introduction:: What is Guix about? * Installation:: Installing Guix. -- cgit v1.2.3 From a827c623cad411a5a177ee23c1292dac914e441f Mon Sep 17 00:00:00 2001 From: Nikita Karetnikov Date: Fri, 30 Aug 2013 16:31:20 +0000 Subject: doc: Remove an extra space after @ref. --- doc/guix.texi | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index 346685040a..9a4f1fb314 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1696,7 +1696,7 @@ the Python language. 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} +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. -- cgit v1.2.3 From c8c871d184b66212cfacf1c0de16ee799f40fdd9 Mon Sep 17 00:00:00 2001 From: Andreas Enge Date: Sat, 31 Aug 2013 00:02:00 +0200 Subject: doc: Stylistic changes to "Packaging Guidelines" --- doc/guix.texi | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) (limited to 'doc/guix.texi') diff --git a/doc/guix.texi b/doc/guix.texi index 9a4f1fb314..5b91bc2982 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -1597,7 +1597,7 @@ bootstrap)} module. For more information on bootstrapping, 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. @ref{Contributing}, for additional information on how you can +grow. @xref{Contributing}, for additional information on how you can help. Free software packages are usually distributed in the form of @@ -1675,18 +1675,19 @@ discuss ways to deal with trademarks and patents. @node Package Naming @subsection Package Naming -A package has actually two names associated to it: +A package has actually 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 the package manager. +@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 by upstream. For instance, the GNUnet project is packaged -as @code{gnunet}. We do not add @code{lib} prefixes for library packages, -unless these are already part of the official project name. -But see @ref{Python Modules} for special rules concerning modules for +project name chosen upstream. For instance, the GNUnet project is packaged +as @code{gnunet}. We do not add @code{lib} prefixes for library packages, +unless these are already part of the official project name. But see +@ref{Python Modules} for special rules concerning modules for the Python language. @@ -1694,9 +1695,10 @@ the Python language. @subsection Version Numbers 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} +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. @@ -1705,6 +1707,7 @@ 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: + @example (define-public gtk+ (package @@ -1735,6 +1738,7 @@ We currently package Python 2 and Python 3, under the Scheme variable names 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 compiles only with Python 3, we name it @code{python-foo}; if it compiles only with Python 2, we name it -- cgit v1.2.3