From mboxrd@z Thu Jan  1 00:00:00 1970
Received: from eggs.gnu.org ([2001:4830:134:3::10]:54259)
	by lists.gnu.org with esmtp (Exim 4.71)
	(envelope-from <mlureau@redhat.com>) id 1baKh9-0008Jz-SY
	for qemu-devel@nongnu.org; Thu, 18 Aug 2016 06:37:09 -0400
Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71)
	(envelope-from <mlureau@redhat.com>) id 1baKh6-0002Hc-Lh
	for qemu-devel@nongnu.org; Thu, 18 Aug 2016 06:37:07 -0400
Received: from mx6-phx2.redhat.com ([209.132.183.39]:33807)
	by eggs.gnu.org with esmtp (Exim 4.71)
	(envelope-from <mlureau@redhat.com>) id 1baKh6-0002H4-Bq
	for qemu-devel@nongnu.org; Thu, 18 Aug 2016 06:37:04 -0400
Date: Thu, 18 Aug 2016 06:36:59 -0400 (EDT)
From: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau <mlureau@redhat.com>
Message-ID: <649636507.669341.1471516619832.JavaMail.zimbra@redhat.com>
In-Reply-To: <CAFEAcA9ZviCQZpRLUJLGtBKW5gAvL57P5YBEFfHgw1DqL7JXFQ@mail.gmail.com>
References: <1466435940-14648-1-git-send-email-marcandre.lureau@redhat.com>
	<CAFEAcA9ZviCQZpRLUJLGtBKW5gAvL57P5YBEFfHgw1DqL7JXFQ@mail.gmail.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: quoted-printable
Subject: Re: [Qemu-devel] [RFC PATCH] build-sys: add make 'help' target
List-Id: <qemu-devel.nongnu.org>
List-Unsubscribe: <https://lists.nongnu.org/mailman/options/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>
List-Archive: <http://lists.nongnu.org/archive/html/qemu-devel/>
List-Post: <mailto:qemu-devel@nongnu.org>
List-Help: <mailto:qemu-devel-request@nongnu.org?subject=help>
List-Subscribe: <https://lists.nongnu.org/mailman/listinfo/qemu-devel>,
	<mailto:qemu-devel-request@nongnu.org?subject=subscribe>
To: Peter Maydell <peter.maydell@linaro.org>
Cc: =?utf-8?Q?Marc-Andr=C3=A9?= Lureau <marcandre.lureau@redhat.com>, QEMU Developers <qemu-devel@nongnu.org>, Paolo Bonzini <pbonzini@redhat.com>, Michael Roth <mdroth@linux.vnet.ibm.com>

Hi

----- Original Message -----
> On 20 June 2016 at 16:19,  <marcandre.lureau@redhat.com> wrote:
> > From: Marc-Andr=C3=A9 Lureau <marcandre.lureau@redhat.com>
> >
> > Add a make 'help', to print a summary of the main Makefile targets.
> > The format is loosely inspired by Linux make 'help' output.
> >
> > Signed-off-by: Marc-Andr=C3=A9 Lureau <marcandre.lureau@redhat.com>
> > ---
> >  Makefile | 33 +++++++++++++++++++++++++++++++++
> >  1 file changed, 33 insertions(+)
> >
> > diff --git a/Makefile b/Makefile
> > index 53e4119..c6bf3d6 100644
> > --- a/Makefile
> > +++ b/Makefile
> > @@ -666,3 +666,36 @@ endif
> >  -include $(wildcard *.d tests/*.d)
> >
> >  include $(SRC_PATH)/tests/docker/Makefile.include
> > +
> > +.PHONY: help
> > +help:
> > +
> > +       @echo  'Cleaning targets:'
> > +       @echo  '  clean           - Remove most generated files but kee=
p
> > the config'
> > +       @echo  '  distclean       - Remove all generated files'
> > +       @echo  '  dist            - Build a distributable tarball'
>=20
> There's a cute trick which will let us put these help strings
> next to the actual makefile targets, which might make it easier
> for us to remember to update and add them: you have a rune
> something like
> help:    ## Show this help.
>         @fgrep -h "##" $(MAKEFILE_LIST) | fgrep -v fgrep | sed -e 's/\\$$=
//'
>         |
> sed -e 's/##//'
>=20
> and then you can annotate all your targets with their doc strings:
>=20
> check:     ## Run all tests
>=20
> Idea from https://gist.github.com/prwhite/8168133
>=20
> We'd need to elaborate it somewhat to add categories, but you get the
> general idea.
>=20
> Does this seem useful, or like overkill ?

Interesting, in fact I use a similar trick in some of my shell scripts:
https://github.com/elmarco/virgl-ci/blob/master/virgl-test.sh#L258

But tbh, I don't think it's so great, it's a bit overkill indeed.