bug#37850: Glib documentation is missing
Pierre Neidhardt writes:
> Oh, that makes total sense, thanks for the explanation Marius!
>
> Alright, final patch attached.
> Let me know if I should merge on master.
Looks good!
> From 29d27b64fb7bbf96a2ed59a3e1c4179717770f5c Mon Sep 17 00:00:00 2001
> From: Pierre Neidhardt
> Date: Mon, 11 Nov 2019 15:38:11 +0100
> Subject: [PATCH] gnu: Add glib-with-documentation.
>
> * gnu/packages/glib.scm (glib-with-documentation): New variable.
> (glib): Hide package.
This should say (glib)[properties]: ...
[...]
> +(define-public glib-with-documentation
> + ;; glib's doc must be built in a separate package since it requires
> gtk-doc,
> + ;; which in turn depends on glib.
> + (package
> +(inherit glib)
> +(properties '((hidden? . #f)))
Using (alist-delete 'hidden? (package-properties glib)) is more future
proof. :-)
> +(outputs (cons "doc" (package-outputs glib))) ; 20 MiB of GTK-Doc
> reference
> +(native-inputs
> + `(("gtk-doc" ,gtk-doc) ; for the doc
> + ("docbook-xml" ,docbook-xml)
> + ,@(package-native-inputs glib)))
> +(arguments
> + (substitute-keyword-arguments (package-arguments glib)
> + ((#:configure-flags flags ''())
> +`(cons "-Dgtk_doc=true" ,flags))
> + ((#:phases phases)
> +`(modify-phases ,phases
> + (add-after 'unpack 'make-local-docbook-xml
> + (lambda* (#:key inputs #:allow-other-keys)
> + (let ((replace-http
> + (lambda (file)
> +(substitute* file
> + ;; Warning: gio.xml uses docbook 4.2, hence the
> "4.." pattern.
> +
> (("http://www.oasis-open.org/docbook/xml/4../docbookx.dtd";)
> + (string-append (assoc-ref inputs "docbook-xml")
> +
> "/xml/dtd/docbook/docbookx.dtd"))
> + (replace-http "gio/gdbus-2.0/codegen/codegen_docbook.py")
> + (for-each replace-http (find-files "." "\\.xml$"))
> + #t)))
Can this phase be removed if you add 'libxml2' to inputs (for the
$XML_CATALOG_FILES search path)?
Otherwise LGTM!
signature.asc
Description: PGP signature
bug#37850: Glib documentation is missing
Oh, that makes total sense, thanks for the explanation Marius!
Alright, final patch attached.
Let me know if I should merge on master.
--
Pierre Neidhardt
https://ambrevar.xyz/
signature.asc
Description: PGP signature
>From 29d27b64fb7bbf96a2ed59a3e1c4179717770f5c Mon Sep 17 00:00:00 2001
From: Pierre Neidhardt
Date: Mon, 11 Nov 2019 15:38:11 +0100
Subject: [PATCH] gnu: Add glib-with-documentation.
* gnu/packages/glib.scm (glib-with-documentation): New variable.
(glib): Hide package.
---
gnu/packages/glib.scm | 40
1 file changed, 40 insertions(+)
diff --git a/gnu/packages/glib.scm b/gnu/packages/glib.scm
index b3e85f8df9..47e4f7006a 100644
--- a/gnu/packages/glib.scm
+++ b/gnu/packages/glib.scm
@@ -339,6 +339,7 @@ shared NFS home directories.")
(variable "GIO_EXTRA_MODULES")
(files '("lib/gio/modules")
(search-paths native-search-paths)
+ (properties '((hidden? . #t)) )
(synopsis "Thread-safe general utility library; basis of GTK+ and GNOME")
(description
@@ -348,6 +349,45 @@ dynamic loading, and an object system.")
(home-page "https://developer.gnome.org/glib/";)
(license license:lgpl2.1+)))
+(define-public glib-with-documentation
+ ;; glib's doc must be built in a separate package since it requires gtk-doc,
+ ;; which in turn depends on glib.
+ (package
+(inherit glib)
+(properties '((hidden? . #f)))
+(outputs (cons "doc" (package-outputs glib))) ; 20 MiB of GTK-Doc reference
+(native-inputs
+ `(("gtk-doc" ,gtk-doc) ; for the doc
+ ("docbook-xml" ,docbook-xml)
+ ,@(package-native-inputs glib)))
+(arguments
+ (substitute-keyword-arguments (package-arguments glib)
+ ((#:configure-flags flags ''())
+`(cons "-Dgtk_doc=true" ,flags))
+ ((#:phases phases)
+`(modify-phases ,phases
+ (add-after 'unpack 'make-local-docbook-xml
+ (lambda* (#:key inputs #:allow-other-keys)
+ (let ((replace-http
+ (lambda (file)
+(substitute* file
+ ;; Warning: gio.xml uses docbook 4.2, hence the "4.." pattern.
+ (("http://www.oasis-open.org/docbook/xml/4../docbookx.dtd";)
+ (string-append (assoc-ref inputs "docbook-xml")
+ "/xml/dtd/docbook/docbookx.dtd"))
+ (replace-http "gio/gdbus-2.0/codegen/codegen_docbook.py")
+ (for-each replace-http (find-files "." "\\.xml$"))
+ #t)))
+ (add-after 'install 'move-doc
+ (lambda* (#:key outputs #:allow-other-keys)
+ (let ((out (assoc-ref outputs "out"))
+ (doc (assoc-ref outputs "doc"))
+ (html (string-append "/share/gtk-doc")))
+ (copy-recursively (string-append out html)
+ (string-append doc html))
+ (delete-file-recursively (string-append out html))
+ #t)
+
(define gobject-introspection
(package
(name "gobject-introspection")
--
2.23.0
bug#37850: Glib documentation is missing
Pierre Neidhardt writes: > You are right, something is wrong with substitute-keyword-arguments. The problem is that GLib has no configure-flags from before. I'm not sure why we get no error from substitute-keyword-arguments (is it swallowed? never run?), but if you change this part: (substitute-keyword-arguments (package-arguments glib) ((#:configure-flags flags) `(cons "-Dgtk_doc=true" ,flags))) ...to read like this: (substitute-keyword-arguments (package-arguments glib) ((#:configure-flags flags ''()) `(cons "-Dgtk_doc=true" ,flags))) Then it should work. The difference is that "flags" gets initialized as the empty list when not already set. signature.asc Description: PGP signature
bug#37850: Glib documentation is missing
On Fri, Nov 15, 2019 at 12:17:30PM +0100, Pierre Neidhardt wrote: > You are right, something is wrong with substitute-keyword-arguments. > No, I did not say that, I said that despite substitute-keyword-arguments returning the correct arguments – as is visible by enclosing the args with a call to (error …) –, meson builds with the old arguments. However now you say it works when copying the arguments from Glib, which is strange. Regards, Florian
bug#37850: Glib documentation is missing
On Tue, Nov 12, 2019 at 05:00:40PM +0100, Pierre Neidhardt wrote: > Hmmm, you are right, it does not get built during the install phase. > > I had a look at the bugtracker: > > https://gitlab.gnome.org/GNOME/glib/issues > > Could not find anything related to this. > > Could our Meson build system be buggy? > As a side note, it does not seem to print any command line flags, which > is a bit inconvenient for debugging. Something we could improve at least. > Moving a call to the “error” procedure in various places in the package and Guix’ meson-build-system.scm reveals (I think) that the package arguments are correctly rewritten by substitute-keyword-arguments, but the meson-build procedure from meson-build-system.scm is called with the original package’s args. Regards, Florian
bug#37850: Glib documentation is missing
Sorry for my past unhelpful email. This module is not used by glib. When I try your package, it seems -Dgtk_doc=true is not applied like when manually running meson. I do not understand why. (Manually running it leads to a crash later.) Regards, Florian
bug#37850: Glib documentation is missing
On Mon, Nov 11, 2019 at 10:29:03AM +0100, Pierre Neidhardt wrote: > Sadly the above does not build the doc. > > Looking at the source, it seems that no provision is taken for building > the doc with Meson. I wonder if this is an upstream mistake, but my > knowledge of Meson is very limited and I could be wrong. > > Any idea, anyone? > I have not checked, but https://mesonbuild.com/Gnome-module.html says about gtkdoc > This creates a $module-doc target that can be ran to build docs and > normally these are only built on install. Since GNOME is a big supporter of Meson, I believe they make no mistakes in GLib’s meson files. Regards, Florian
bug#37850: Glib documentation is missing
Hi Marius,
you are right, this seems to be a much saner approach.
So I've tried the following:
- add `(properties '((hidden? . #t)) )` to glib.
- Add the following new package definition:
--8<---cut here---start->8---
(define-public glib-with-documentation
(package
(inherit glib)
(properties '((hidden? . #f)))
(outputs (cons "doc" (package-outputs glib))) ; 20 MiB of GTK-Doc reference
(native-inputs
`(("gtk-doc" ,gtk-doc) ; for the doc
,@(package-native-inputs glib)))
(arguments
(substitute-keyword-arguments (package-arguments glib)
((#:configure-flags flags)
`(cons "-Dgtk_doc=true" ,flags))
;; TODO: Fix 1 failing test.
((#:phases phases)
`(modify-phases ,phases
(delete 'check)))
--8<---cut here---end--->8---
Sadly the above does not build the doc.
Looking at the source, it seems that no provision is taken for building
the doc with Meson. I wonder if this is an upstream mistake, but my
knowledge of Meson is very limited and I could be wrong.
Any idea, anyone?
--
Pierre Neidhardt
https://ambrevar.xyz/
signature.asc
Description: PGP signature
bug#37850: Glib documentation is missing
Pierre Neidhardt writes:
> Marius Bakke writes:
>
>> Pierre Neidhardt writes:
>>
>>> From 893613a3b99c20688cc331d2926dbee28cc143d7 Mon Sep 17 00:00:00 2001
>>> From: Pierre Neidhardt
>>> Date: Sun, 3 Nov 2019 17:36:17 +0100
>>> Subject: [PATCH] gnu: Add glib-minimal and build glib doc.
>>>
>>> glib documentation must be built with gtk-doc which in turn depends on glib,
>>> so we need to define glib-minimal which does not depend on gtk-doc.
>>>
>>> * gnu/packages/glib.scm (glib-minimal): New variable.
>>> (glib)[source]: Don't use `name'.
>>> * gnu/packages/avahi.scm: Use glib-minimal when necessary.
>>> * gnu/packages/cups.scm: Use glib-minimal when necessary.
>>> * gnu/packages/gnome.scm: Use glib-minimal when necessary.
>>> * gnu/packages/graphviz.scm: Use glib-minimal when necessary.
>>> * gnu/packages/gtk.scm: Use glib-minimal when necessary.
>>> * gnu/packages/inkscape.scm: Use glib-minimal when necessary.
>>> * gnu/packages/pdf.scm: Use glib-minimal when necessary.
>>
>> Please mention all changed variables and inputs here, as we always do.
>
> Sure, I didn't because I wasn't sure it was a good idea either :p
>
>> That said, I'm not certain this is a good solution. Why do some
>> packages use glib-minimal and others not? What does "necessary" mean in
>> this context?
>>
>> What about 'hiding' the normal glib package, and expose a
>> 'glib-with-documentation' variant to end users, similar to how the
>> 'cmake' package works?
>
> cmake-minimal builds the doc already, I don't see a
> cmake-with-documentation. Did you mean something else?
> I see a couple packages with the "-documentation" prefix, so we could
> use "glib-documentation".
I meant this part:
(define-public cmake
(package
(inherit cmake-minimal)
(name "cmake")
(arguments
(substitute-keyword-arguments (package-arguments cmake-minimal)
((#:configure-flags configure-flags ''())
`(append ,configure-flags
;; Extra configure flags used to generate the documentation.
'("--sphinx-info"
"--sphinx-man"
"--sphinx-html")))
Do you think it would make sense to do something similar with GLib,
and "hiding" the normal variant?
> In a previous email, I explained that I wanted to put the documentation
> in the "doc" output of glib for 2 reasons:
>
> - For consistency with the other packages from the GTK family.
> - To restore the missing "gtk:doc" output. If I understand correctly,
> we don't have a provision to deprecate outputs, only packages. I
> think this is a bug.
signature.asc
Description: PGP signature
bug#37850: Glib documentation is missing
I missed this part. glib documentation must be built with gtk-doc which in turn depends on glib, so we need to define glib-minimal which does not depend on gtk-doc. In this case the way I have seen other distros do it is by having a *-bootstrap package (same as the *-minimal that you mention), which doesn't sound like a bad approach. What about 'hiding' the normal glib package Maybe the *-bootstrap package can be hidden. Then the normal glib package can have its "doc" back?
bug#37850: Glib documentation is missing
I am new to guix so please excuse my ignorance, but is there an issue with just adding a "doc" output to the current glib, as mentioned in the manual? http://guix.gnu.org/manual/en/guix.html#Packages-with-Multiple-Outputs I find this approach nice and clean and I am personally not too fond of the idea of having "*-minimal" and "*-with-documentation" packages.
bug#37850: Glib documentation is missing
Pierre Neidhardt writes: > From 893613a3b99c20688cc331d2926dbee28cc143d7 Mon Sep 17 00:00:00 2001 > From: Pierre Neidhardt > Date: Sun, 3 Nov 2019 17:36:17 +0100 > Subject: [PATCH] gnu: Add glib-minimal and build glib doc. > > glib documentation must be built with gtk-doc which in turn depends on glib, > so we need to define glib-minimal which does not depend on gtk-doc. > > * gnu/packages/glib.scm (glib-minimal): New variable. > (glib)[source]: Don't use `name'. > * gnu/packages/avahi.scm: Use glib-minimal when necessary. > * gnu/packages/cups.scm: Use glib-minimal when necessary. > * gnu/packages/gnome.scm: Use glib-minimal when necessary. > * gnu/packages/graphviz.scm: Use glib-minimal when necessary. > * gnu/packages/gtk.scm: Use glib-minimal when necessary. > * gnu/packages/inkscape.scm: Use glib-minimal when necessary. > * gnu/packages/pdf.scm: Use glib-minimal when necessary. Please mention all changed variables and inputs here, as we always do. That said, I'm not certain this is a good solution. Why do some packages use glib-minimal and others not? What does "necessary" mean in this context? What about 'hiding' the normal glib package, and expose a 'glib-with-documentation' variant to end users, similar to how the 'cmake' package works? signature.asc Description: PGP signature
bug#37850: Glib documentation is missing
Ludovic Courtès writes: > Alternately, we could define a new “glib-doc” package that would depend > on the current “glib” package, assuming the build system allows us to > build nothing but documentation. Some possible drawbacks: - It's not consistent with the other Glib/GNOME libraries like gtk+ or webkitgtk which have a "doc" output. - Previously we had glib:doc and no measure can be taken to let the user know that it's now "glib-doc". So I would got for the glib-minimal route. This bring me to another problem: "glib:doc" was not deprecated, so users who installed "glib:doc" cannot update their manifests / profiles after a guix pull. Can we actually deprecate single outputs? If not, isn't it a bug? -- Pierre Neidhardt https://ambrevar.xyz/ signature.asc Description: PGP signature
bug#37850: Glib documentation is missing
Hi, Pierre Neidhardt skribis: > Marius Bakke writes: [...] >> 'gtk-doc' unsurprisingly depends on GLib, so I'm not sure what the best >> approach is. > > What about the following: > > 1. Turn our current glib into glib-minimal. > > 2. Build gtk-doc against glib-minimal. > > 3. Define a new glib package that inherits from glib-minimal and adds > gtk-doc as native-inputs so that we can restore the "doc" output. Alternately, we could define a new “glib-doc” package that would depend on the current “glib” package, assuming the build system allows us to build nothing but documentation. Ludo’.
bug#37850: Glib documentation is missing
Pierre Neidhardt writes: > Since the last core-update merge, glib 2.58.1+ does not include the > documentation anymore (it was in the "doc" output). > > Documentation for Glib/GTK-based libraries is very useful for > developers: it allows offline and contextual access from any text > editor. > > This is why it would be nice to include it back. > > Commit 6c237a2d7bfa3c7be02c069e5c24a2b401a51864 (June 21st) states > > --8<---cut here---start->8--- > [outputs]: Remove "doc" as the documentation files are no longer included. > --8<---cut here---end--->8--- > > However looking at the source of Glib I cannot find trace of this in the > NEWS file nor in the INSTALL.in file. Disclaimer: I haven't tried > building glib. > > Maybe we miss a compilation flag? Installing the GLib documentation now requires 'gtk-doc' at build time: https://gitlab.gnome.org/GNOME/glib/blob/master/meson_options.txt 'gtk-doc' unsurprisingly depends on GLib, so I'm not sure what the best approach is. signature.asc Description: PGP signature
bug#37850: Glib documentation is missing
Since the last core-update merge, glib 2.58.1+ does not include the documentation anymore (it was in the "doc" output). Documentation for Glib/GTK-based libraries is very useful for developers: it allows offline and contextual access from any text editor. This is why it would be nice to include it back. Commit 6c237a2d7bfa3c7be02c069e5c24a2b401a51864 (June 21st) states --8<---cut here---start->8--- [outputs]: Remove "doc" as the documentation files are no longer included. --8<---cut here---end--->8--- However looking at the source of Glib I cannot find trace of this in the NEWS file nor in the INSTALL.in file. Disclaimer: I haven't tried building glib. Maybe we miss a compilation flag? What do you think? Ricardo? Cheers! -- Pierre Neidhardt https://ambrevar.xyz/ signature.asc Description: PGP signature
