No olvides que en las ciencias informáticas un problema casi siempere puede tener más de una soluciones, pero nosotros aquí te compartiremos lo mejor y más eficiente.
Solución:
La siguiente es una solución más simple que no requiere definir funciones de usuario ni agregar texto de ayuda fuera de las reglas que documentan.
# 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.
Corriendo make o make help da como resultado lo siguiente:
----------------------------------------------------------------------
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.
Un buen toque es proporcionar un falso help objetivo que imprime un resumen de objetivos y opciones. Desde el kernel de 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 ''
Puede ser un poco de trabajo mantener la documentación de esta manera, pero creo que separa muy bien lo que está destinado a los “usuarios” frente a lo que está destinado a las personas que mantienen el Makefile en sí mismo (comentarios en línea).
Creé mi propia solución utilizando un breve script de Perl que formatea la ayuda como otras herramientas de 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."
Lo que da esto:
$ 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.
valoraciones y comentarios
No se te olvide compartir este artículo si te valió la pena.