2012-01-17 7 views
6

C'è un modo per scrivere commenti "standard" in un Makefile per poi inviarli a un programma simile a Doxygen in modo da produrre una buona documentazione (HTML o man per esempio)? Mi piacerebbe avere una visione chiara dei miei obiettivi principali da qualche parte ma niente di troppo.Come documentare un makefile?

risposta

5

Un bel tocco è quello di fornire un falso bersaglio help che stampa un riepilogo di obiettivi e opzioni. Dal kernel Linux Makefile:

help: 
     @echo 'Cleaning targets:' 
     @echo ' clean   - Remove most generated files but keep the config and' 
     @echo '     enough build support to build external modules' 
     @echo ' mrproper  - Remove all generated files + config + various backup files' 
     @echo ' distclean  - mrproper + remove editor backup and patch files' 
     @echo '' 
     @echo 'Configuration targets:' 
     @$(MAKE) -f $(srctree)/scripts/kconfig/Makefile help 
     @echo '' 

Potrebbe essere un po 'di lavoro per mantenere la documentazione in questo modo, ma mi trovo bene separa ciò che è destinato a "utenti" rispetto a ciò che è destinato a persone mantenendo la Makefile sé (commenti in linea).

+0

Forse non sono abbastanza paziente, ma dubito che ci sia qualcosa di altro oltre a quello che si menzionate. Grazie molto !! –

+0

Se vuoi qualche tipo di materiale automatico dai un'occhiata a [make-help] (https://github.com/gibatronic/make-help). – gibatronic

1

Self-Documenting Makefiles (John Graham-Cumming, 2005) consente di scrivere l'aiuto accanto a ciascuna regola. Questa è una soluzione leggera e molto ingegnosa che funziona almeno con GNU Make.

Ecco il mio slightly modified version (def-help-section consente di organizzare lunghi elenchi di regole).

1

ho fatto la mia soluzione con un breve script Perl che formattare l'aiuto di altri strumenti GNU:

SCRIPT_VERSION=v1.0 
SCRIPT_AUTHOR=John Doe 

all:    ##@Build Build all the project 

clean:    ##@Cleaning Remove all intermediate objects 

mrproper: clean  ##@Cleaning Remove all output and interemediate objects 

HELP_FUN = \ 
    %help; while(<>){[email protected]{$$help{$$2//'options'}},[$$1,$$3] \ 
    if/^([\w-_]+)\s*:.*\#\#(?:@(\w+))?\s(.*)$$/}; \ 
    print"$$_:\n", map" $$_->[0]".(" "x(20-length($$_->[0])))."$$_->[1]\n",\ 
    @{$$help{$$_}},"\n" for keys %help; \ 

help: ##@Miscellaneous Show this help 
    @echo -e "Usage: make [target] ...\n" 
    @perl -e '$(HELP_FUN)' $(MAKEFILE_LIST) 
    @echo -e "Written by $(SCRIPT_AUTHOR), version $(SCRIPT_VERSION)" 
    @echo -e "Please report any bug or error to the author." 

che dà questo:

$ make help 
Usage: make [target] ... 

Miscellaneous: 
    help    Show this help 

Build: 
    all     Build all the project 

Cleaning: 
    clean    Remove all intermediate objects 
    mrproper   Remove all output and interemediate objects 

Written by John Doe, version v1.0 
Please report any bug or error to the author. 
+1

Un piccolo miglioramento per il bit HELP_FUN: sostituire 'if/^ (\ w +) \ s *:' con 'if/^ ([\ w -_] +) \ s *:' per consentire target del tipo "this-target" o "that_target" pure. – th3n3rd

1

Quello che segue è una soluzione più semplice che non lo fa richiede la definizione di funzioni utente o l'aggregazione del testo di aiuto lontano dalle regole che documentano.

# This is a regular comment, that will not be displayed 

## ---------------------------------------------------------------------- 
## This is a help comment. The purpose of this Makefile is to demonstrate 
## a simple help mechanism that uses comments defined alongside the rules 
## they describe without the need of additional help files or echoing of 
## descriptions. Help comments are displayed in the order defined within 
## the Makefile. 
## ---------------------------------------------------------------------- 

help:  ## Show this help. 
    @sed -ne '/@sed/!s/## //p' $(MAKEFILE_LIST) 

build: ## Build something. 

install: ## Install something. 

deploy: ## Deploy something. 

format: ## Help comments are display with their leading whitespace. For 
      ## example, all comments in this snippet are aligned with spaces. 

esecuzione make o make help risultati nella seguente:

---------------------------------------------------------------------- 
This is a help comment. The purpose of this Makefile is to demonstrate 
a simple help mechanism that uses comments defined alongside the rules 
they describe without the need of additional help files or echoing of 
descriptions. Help comments are displayed in the order defined within 
the Makefile. 
---------------------------------------------------------------------- 
help:  Show this help. 
build: Build something. 
install: Install something. 
deploy: Deploy something. 
format: Help comments are display with their leading whitespace. For 
      example, all comments in this snippet are aligned with spaces.