unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Makefile logic to create Guix documentation
@ 2020-06-14  0:48 Chris Marusich
  2020-06-14  3:12 ` Julien Lepiller
  2020-06-16  9:40 ` Ludovic Courtès
  0 siblings, 2 replies; 5+ messages in thread
From: Chris Marusich @ 2020-06-14  0:48 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: guix-devel

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

Hi Ludo,

I was reading through the Makefile that creates the documentation, and I
came across some parts I couldn't understand, even though I spent a few
hours trying to figure it out.  I thought you might know the answers to
my questions off the top of your head, since I think you wrote it.

First, consider this snippet from doc/local.mk:

--8<---------------cut here---------------start------------->8---
# We cannot add new dependencies to `%D%/guix.pdf' & co. (info "(automake)
# Extending").  Using the `-local' rules is imperfect, because they may be
# triggered after the main rule.  Oh, well.
pdf-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.pdf)
info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png)
ps-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps)		\
	  $(top_srcdir)/%D%/images/coreutils-size-map.eps
dvi-local: ps-local
--8<---------------cut here---------------end--------------->8---

What is this syntax called?  I checked the Make, Automake, and Autoconf
manuals, but I couldn't find anything.  I'm talking about this syntax:

  info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png)

It looks like when you added this, you intended to add a *.png
prerequisite to the info-local target for every equivalent *.dot file
that exists.  My guess is you want to ensure that the PNG files are
generated before the info page gets created, since the PNG files are
required in order to build the info page.  However, is it possible you
meant to write it like the following instead?  (The first "=" has been
replaced with a ":".)

  info-local: $(DOT_FILES:%.dot=$(top_srcdir)/%.png)
                         
When using ":", I recognize this syntax as a "substitution reference"
(see: (make) Substitution Refs).  However, I do not know what it is
supposed to be when the ":" is replaced with a "=".  Is it a typo?

I experimented by adding a snippet like the following to the generated
Makefile...

--8<---------------cut here---------------start------------->8---
marucustom: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps)
	@echo XXXXX expansion is: _$(DOT_FILES=%.dot=$(top_srcdir)/%.eps)_
	@echo XXXXX prerequisite: $<
	@echo XXXXX target: $@
--8<---------------cut here---------------end--------------->8---

...and it seems to cause make to substitute an empty string:

--8<---------------cut here---------------start------------->8---
$ make marucustom
XXXXX expansion is: __
XXXXX prerequisite:
XXXXX target: marucustom
--8<---------------cut here---------------end--------------->8---

Second, I noticed some rules like the following:

--8<---------------cut here---------------start------------->8---
.dot.eps:
	$(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \
	mv "$(srcdir)/$@.tmp" "$(srcdir)/$@"
--8<---------------cut here---------------end--------------->8---

What I do understand is that AM_V_DOT and DOT are set in Makefile.am and
configure.ac, and that they are used to invoke the "dot" program.
However, I couldn't quite understand the rest of this rule.

Why are there no prerequisites?  It looks like the rule doesn't declare
any prerequisites, so I'm confused about why the recipe includes
references to the name of the first prerequisite ("$<").

What causes this rule to be run?  I tried adding echo commands in the
recipe like so...

--8<---------------cut here---------------start------------->8---
.dot.eps:
	@echo YYYYY .dot.eps is running
	@echo YYYYY target: %@
	@echo YYYYY prerequisite: _$<_
	$(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \
	mv "$(srcdir)/$@.tmp" "$(srcdir)/$@"
--8<---------------cut here---------------end--------------->8---

...but I didn't see new messages when I ran "make" (from a clean
checkout).  Maybe I didn't invoke make correctly.

If you or anyone else could point out if I'm missing something, that'd
be really helpful.  Thank you in advance!

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Makefile logic to create Guix documentation
  2020-06-14  0:48 Makefile logic to create Guix documentation Chris Marusich
@ 2020-06-14  3:12 ` Julien Lepiller
  2020-06-14  5:08   ` Chris Marusich
  2020-06-16  9:40 ` Ludovic Courtès
  1 sibling, 1 reply; 5+ messages in thread
From: Julien Lepiller @ 2020-06-14  3:12 UTC (permalink / raw)
  To: guix-devel, Chris Marusich, Ludovic Courtès

Le 13 juin 2020 20:48:21 GMT-04:00, Chris Marusich <cmmarusich@gmail.com> a écrit :
>Hi Ludo,
>
>I was reading through the Makefile that creates the documentation, and
>I
>came across some parts I couldn't understand, even though I spent a few
>hours trying to figure it out.  I thought you might know the answers to
>my questions off the top of your head, since I think you wrote it.
>
>First, consider this snippet from doc/local.mk:
>
>--8<---------------cut here---------------start------------->8---
># We cannot add new dependencies to `%D%/guix.pdf' & co. (info
>"(automake)
># Extending").  Using the `-local' rules is imperfect, because they may
>be
># triggered after the main rule.  Oh, well.
>pdf-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.pdf)
>info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png)
>ps-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps)		\
>	  $(top_srcdir)/%D%/images/coreutils-size-map.eps
>dvi-local: ps-local
>--8<---------------cut here---------------end--------------->8---
>
>What is this syntax called?  I checked the Make, Automake, and Autoconf
>manuals, but I couldn't find anything.  I'm talking about this syntax:
>
>  info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png)
>
>It looks like when you added this, you intended to add a *.png
>prerequisite to the info-local target for every equivalent *.dot file
>that exists.  My guess is you want to ensure that the PNG files are
>generated before the info page gets created, since the PNG files are
>required in order to build the info page.  However, is it possible you
>meant to write it like the following instead?  (The first "=" has been
>replaced with a ":".)
>
>  info-local: $(DOT_FILES:%.dot=$(top_srcdir)/%.png)
>                         
>When using ":", I recognize this syntax as a "substitution reference"
>(see: (make) Substitution Refs).  However, I do not know what it is
>supposed to be when the ":" is replaced with a "=".  Is it a typo?
>
>I experimented by adding a snippet like the following to the generated
>Makefile...
>
>--8<---------------cut here---------------start------------->8---
>marucustom: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps)
>	@echo XXXXX expansion is: _$(DOT_FILES=%.dot=$(top_srcdir)/%.eps)_
>	@echo XXXXX prerequisite: $<
>	@echo XXXXX target: $@
>--8<---------------cut here---------------end--------------->8---
>
>...and it seems to cause make to substitute an empty string:
>
>--8<---------------cut here---------------start------------->8---
>$ make marucustom
>XXXXX expansion is: __
>XXXXX prerequisite:
>XXXXX target: marucustom
>--8<---------------cut here---------------end--------------->8---
>
>Second, I noticed some rules like the following:
>
>--8<---------------cut here---------------start------------->8---
>.dot.eps:
>	$(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \
>	mv "$(srcdir)/$@.tmp" "$(srcdir)/$@"
>--8<---------------cut here---------------end--------------->8---
>
>What I do understand is that AM_V_DOT and DOT are set in Makefile.am
>and
>configure.ac, and that they are used to invoke the "dot" program.
>However, I couldn't quite understand the rest of this rule.
>
>Why are there no prerequisites?  It looks like the rule doesn't declare
>any prerequisites, so I'm confused about why the recipe includes
>references to the name of the first prerequisite ("$<").
>
>What causes this rule to be run?  I tried adding echo commands in the
>recipe like so...
>
>--8<---------------cut here---------------start------------->8---
>.dot.eps:
>	@echo YYYYY .dot.eps is running
>	@echo YYYYY target: %@
>	@echo YYYYY prerequisite: _$<_
>	$(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \
>	mv "$(srcdir)/$@.tmp" "$(srcdir)/$@"
>--8<---------------cut here---------------end--------------->8---
>
>...but I didn't see new messages when I ran "make" (from a clean
>checkout).  Maybe I didn't invoke make correctly.
>
>If you or anyone else could point out if I'm missing something, that'd
>be really helpful.  Thank you in advance!

Not sure for the rest, but .dot.eps: is similar to:

%.eps: %.dot

You often find .c.o in Makefiles for instance.


^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Makefile logic to create Guix documentation
  2020-06-14  3:12 ` Julien Lepiller
@ 2020-06-14  5:08   ` Chris Marusich
  0 siblings, 0 replies; 5+ messages in thread
From: Chris Marusich @ 2020-06-14  5:08 UTC (permalink / raw)
  To: Julien Lepiller; +Cc: guix-devel

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

Hi Julien,

Julien Lepiller <julien@lepiller.eu> writes:

> Not sure for the rest, but .dot.eps: is similar to:
>
> %.eps: %.dot
>
> You often find .c.o in Makefiles for instance.

Ohhh, I see!  With this info, I was able to determine that the relevant
information is documented, but I just missed it (see: (make) Suffix
Rules).  Thank you very much for pointing it out to me!

I'm still not sure about the rest, though...  Maybe Ludo knows.

-- 
Chris

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 832 bytes --]

^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Makefile logic to create Guix documentation
  2020-06-14  0:48 Makefile logic to create Guix documentation Chris Marusich
  2020-06-14  3:12 ` Julien Lepiller
@ 2020-06-16  9:40 ` Ludovic Courtès
  2020-06-16 15:02   ` zimoun
  1 sibling, 1 reply; 5+ messages in thread
From: Ludovic Courtès @ 2020-06-16  9:40 UTC (permalink / raw)
  To: Chris Marusich; +Cc: guix-devel

Hi,

Chris Marusich <cmmarusich@gmail.com> skribis:

> First, consider this snippet from doc/local.mk:
>
> # We cannot add new dependencies to `%D%/guix.pdf' & co. (info "(automake)
> # Extending").  Using the `-local' rules is imperfect, because they may be
> # triggered after the main rule.  Oh, well.
> pdf-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.pdf)
> info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png)
> ps-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.eps)		\
> 	  $(top_srcdir)/%D%/images/coreutils-size-map.eps
> dvi-local: ps-local
>
>
> What is this syntax called?  I checked the Make, Automake, and Autoconf
> manuals, but I couldn't find anything.  I'm talking about this syntax:
>
>   info-local: $(DOT_FILES=%.dot=$(top_srcdir)/%.png)

These are GNU Make substitutions (info "(make) Substitution Refs").

> It looks like when you added this, you intended to add a *.png
> prerequisite to the info-local target for every equivalent *.dot file
> that exists.  My guess is you want to ensure that the PNG files are
> generated before the info page gets created, since the PNG files are
> required in order to build the info page.  However, is it possible you
> meant to write it like the following instead?  (The first "=" has been
> replaced with a ":".)
>
>   info-local: $(DOT_FILES:%.dot=$(top_srcdir)/%.png)
>                          
> When using ":", I recognize this syntax as a "substitution reference"
> (see: (make) Substitution Refs).  However, I do not know what it is
> supposed to be when the ":" is replaced with a "=".  Is it a typo?

Ah yes, definitely!  I didn’t even notice when reading it above.
You’re welcome to make that change if nothing bad happens!

> Second, I noticed some rules like the following:
>
> .dot.eps:
> 	$(AM_V_DOT)$(DOT) -Teps $(DOT_OPTIONS) < "$<" > "$(srcdir)/$@.tmp"; \
> 	mv "$(srcdir)/$@.tmp" "$(srcdir)/$@"

Julien already replied; this is POSIX make notation.

Thanks,
Ludo’.


^ permalink raw reply	[flat|nested] 5+ messages in thread

* Re: Makefile logic to create Guix documentation
  2020-06-16  9:40 ` Ludovic Courtès
@ 2020-06-16 15:02   ` zimoun
  0 siblings, 0 replies; 5+ messages in thread
From: zimoun @ 2020-06-16 15:02 UTC (permalink / raw)
  To: Ludovic Courtès, Chris Marusich; +Cc: guix-devel

Hi,

Speaking about Makefile and Guix documentation, I have remarked things
(maybe I am doing wrong) that annoys me time to time.

1. "make info" is not self consistent.

--8<---------------cut here---------------start------------->8---
./doc/guix.texi:11297: @include: could not find os-config-bare-bones.texi
./doc/guix.texi:11438: @include: could not find os-config-desktop.texi
./doc/guix.texi:11445: @include: could not find os-config-lightweight-desktop.texi
make[1]: *** [Makefile:4078: doc/guix.info] Error 1
--8<---------------cut here---------------end--------------->8---


2. I am always confused how to generate the EPS/PNG of "doc/images" and
   generally I end up with "make ... wait C-c".


3. The modified PO files under "po/{guix,packages}/" hangs Magit and
   then Emacs so generally I have to restore them before going back to
   Magit.
   

I am not enough annoyed to unwrap the logic of Makefile and propose a
patch but if someone is visiting the topic... Or maybe a tips for
improving my workflow. :-)


All the best,
simon


^ permalink raw reply	[flat|nested] 5+ messages in thread

end of thread, other threads:[~2020-06-16 15:18 UTC | newest]

Thread overview: 5+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-06-14  0:48 Makefile logic to create Guix documentation Chris Marusich
2020-06-14  3:12 ` Julien Lepiller
2020-06-14  5:08   ` Chris Marusich
2020-06-16  9:40 ` Ludovic Courtès
2020-06-16 15:02   ` zimoun

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).