¿Hay alguna manera de escribir comentarios "estándar" en un archivo Makefile para luego alimentarlos a un programa parecido a Doxygen a fin de generar una buena documentación (HTML u otro por ejemplo)? Me gustaría tener una visión clara de mis objetivos principales en algún lugar, pero nada demasiado elegante.Cómo documentar un archivo MAKE?
Respuesta
Un buen toque es proporcionar un objetivo falso help
que imprime un resumen de objetivos y opciones. Desde el núcleo 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 que sea un poco de trabajo para mantener la documentación de esta manera, pero me parece muy bien separa lo que está destinado a "usuarios" frente a lo que está previsto para la gente mantener la Makefile
propio (comentarios en línea).
Self-Documenting Makefiles (John Graham-Cumming, 2005) le permite escribir la ayuda junto con cada regla. Esta es una solución ligera y altamente ingeniosa que funciona al menos con GNU Make.
Aquí está mi slightly modified version (def-help-section ayuda a organizar largas listas de reglas).
hice mi propia solución utilizando un pequeño script en Perl que formatear la ayuda de otras herramientas 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."
que da a esta:
$ 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.
Una pequeña mejora en el bit HELP_FUN: reemplace 'if/^ (\ w +) \ s *:' con 'if/^ ([\ w -_] +) \ s *:' para permitir destinos del tipo "this-target" o "that_target" también. – th3n3rd
La siguiente es una solución más simple que no lo hace requieren definir funciones de usuario o 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.
Correr make
o make help
resultados en 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.
- 1. ¿Cómo ejecutar un archivo MAKE en Windows?
- 2. Cómo comprobar si un archivo existe en un archivo MAKE
- 3. Obtener el nombre del archivo MAKE del archivo MAKE
- 4. extensión de archivo MAKE
- 5. cómo documentar un paquete python
- 6. Cómo fuerza un archivo MAKE a reconstruir un objetivo
- 7. extensión de archivo MAKE
- 8. Depende del archivo make
- 9. ¿Por qué GNU make eliminar un archivo
- 10. ¿Qué significa "todo" en un archivo MAKE?
- 11. Creación de un archivo MAKE FORTRAN
- 12. ¿Cómo puedo escribir un archivo MAKE para autodetectar y paralelizar la compilación con GNU Make?
- 13. ¿Cómo escribo el comando 'cd' en un archivo MAKE?
- 14. ¿Cómo detectar el sistema operativo en un archivo make?
- 15. ¿Cómo realizo la aritmética en un archivo MAKE?
- 16. ¿Cómo configurar un archivo MAKE en Eclipse (C++)?
- 17. ¿Cómo se especifica RPATH en un archivo MAKE?
- 18. cómo usar un archivo make para mingw en win32
- 19. ejecutando un script bash desde un archivo make
- 20. ¿Cómo puedo documentar un C# dll
- 21. ¿Cómo documentar un tipo de pato?
- 22. ¿Cómo documentar un proyecto de Python?
- 23. ¿Cómo creo un archivo MAKE a partir de un archivo de solución de Visual Studio?
- 24. ¿Qué hace un símbolo de porcentaje en un archivo MAKE?
- 25. ¿Puede un archivo MAKE tener un directorio como destino?
- 26. ¿Por qué este archivo MAKE ejecuta un objetivo en 'make clean'
- 27. Exportar un archivo MAKE de bloques de código
- 28. Creando dos ejecutables separados de un archivo MAKE (g ++)
- 29. autoconf no genera el archivo MAKE?
- 30. Pasando un indicador de gcc a través del archivo MAKE
Tal vez no soy lo suficientemente paciente, pero dudo que haya algo más, aparte de lo que lo mencionan. Muchas gracias !! –
Si desea algún tipo de material automatizado, eche un vistazo a [make-help] (https://github.com/gibatronic/make-help). – gibatronic