Zerocat Chipflasher  v0.4.10-182-333b622f
Flash free firmware to BIOS chips, kick the Management Engine.
Makefile File Reference

Generate the Chipflasher’s HTML documentation with doxygen. More...

Detailed Description

Code

##>! @file
##>!
##>! @brief Generate the Chipflasher’s HTML documentation with doxygen.
##>!
##>! # Copyright
##>!
##>! Zerocat Chipflasher --- Flash free firmware to BIOS chips,
##>!                         kick the Management Engine.
##>!
##>! Copyright (C) 2016-2018, 2020, 2021 Kai Mertens <kmx@posteo.net>@n
##>! Copyright (C) 2016 rekado <rekado@elephly.net>
##>!
##>! The Zerocat Chipflasher is free software: you can redistribute it
##>! and/or modify it under the terms of the GNU General Public License
##>! as published by the Free Software Foundation, either version 3 of
##>! the License, or (at your option) any later version.
##>!
##>! The Zerocat Chipflasher is distributed in the hope that it will be
##>! useful, but WITHOUT ANY WARRANTY; without even the implied warranty
##>! of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
##>! GNU General Public License for more details.
##>!
##>! You should have received a copy of the GNU General Public License
##>! along with this program.  If not, see <http://www.gnu.org/licenses/>.
##>!
##>! This file is part of the Zerocat Chipflasher.
##>!
##>! # “In file” Documentation
##>!
##>! ## Usage
##>!
##>!     $ make help
##>!
##>! @cond
#

# Shell
SHELL                         := /bin/sh

# White Space
EMPTY                         :=
SPACE                         := $(EMPTY) $(EMPTY)
COMMA                         := ,
M5                            := xxxxx
TAB1                          := \r\t\t
TAB2                          := \r\t\t\t

# Suffixes
.SUFFIXES :
.SUFFIXES : .orig

# Utilities
RM                            := $(shell command -v rm)
RMFLAGS                       :=
$(if $(strip $(RM)),,         $(error Cannot find rm utility))

CP                            := $(shell command -v cp)
CPFLAGS                       :=
$(if $(strip $(CP)),,         $(error Cannot find cp utility))

SET                           := $(shell command -v set)
SETFLAGS                      := -f
$(if $(strip $(SET)),,        $(error Cannot find set utility))

GIT                           := $(shell command -v git)
GITFLAGS                      :=
$(if $(strip $(GIT)),,        $(error Cannot find git utility))

#   Note ‘mkdir -p’ might not be supported.
MKDIR                         := $(shell command -v mkdir)
MKDIRFLAGS                    := -p
$(if $(strip $(MKDIR)),,      $(error Cannot find mkdir utility))

SED                           := $(shell command -v sed)
SEDFLAGS                      := -r
$(if $(strip $(SED)),,        $(error Cannot find sed utility))

ECHO                          := $(shell command -v echo)
ECHOFLAGS                     := -e
$(if $(strip $(ECHO)),,       $(error Cannot find echo utility))

DOXYGEN                       := $(shell command -v doxygen)
DOXYGENFLAGS                  := -s
$(if $(strip $(DOXYGEN)),,    $(error Cannot find doxygen utility))

# Root Paths
ROOT_RESOURCES                := doxygen-resources/
ROOT_HARDWARE                 := ../hardware/
ROOT_HARDWARE_ARTWORK         := $(ROOT_HARDWARE)artwork/
ROOT_HARDWARE_GSCHEM          := $(ROOT_HARDWARE)gschem/
ROOT_HARDWARE_PCB             := $(ROOT_HARDWARE)pcb/
ROOT_GENERATED_FILES          := generated-files/
ROOT_GENERATED_IMAGES         := generated-images/
ROOT_GENERATED_DOCUMENTATION  := generated-documentation/
ROOT_GENERATED_HTML           := $(ROOT_GENERATED_DOCUMENTATION)html/

# Sources
FAVICON                       := $(ROOT_RESOURCES)favicon.png
MAINPAGE                      := frontpage.md
DOXYORIG                      := $(ROOT_RESOURCES)Doxyfile.orig
PROJECT_LOGO                  := $(ROOT_RESOURCES)zerocat-logo-0D0D1A-90dpi.png
HTML_EXTRA_STYLESHEET         := $(ROOT_RESOURCES)zerocat-style.css

# Targets
INDEX_HTML                    := $(ROOT_GENERATED_HTML)index.html
DOXYFILE                      := $(ROOT_RESOURCES)Doxyfile
HTML_HEADER                   := $(ROOT_RESOURCES)header.html
HTML_FOOTER                   := $(ROOT_RESOURCES)footer.html
HTML_STYLESHEET               := $(ROOT_RESOURCES)style.css
HTML_HEADER_ICON              := $(addsuffix .icon,$(HTML_HEADER))
#   Locate generated markdown files within doc source folder to make them
#   visible for Doxygen’s markdown integrator.
BOM_MD_BOARD                  := board.bom.md
BOM_MD_CABLES                 := cables.bom.md

# Settings
WARN_LOGFILE                  := $(ROOT_RESOURCES)doxygen.log
DOXYGEN_VERSION               := $(shell $(DOXYGEN) $(DOXYGENFLAGS) --version)
PROJECT_BRIEF                 := \"Flash free firmware to BIOS chips, kick the Management Engine.\"
PROJECT_NUMBER                := $(shell $(strip \
	$(SET) $(SETFLAGS); \
	$(GIT) $(GITFLAGS) \
		describe \
			--match v* | \
	$(SED) $(SEDFLAGS) \
		-e 's/(.*)(-g)([0-9a-f]*)/\1-\3/;' \
			-; \
	))
HTML_OUTPUT                   := $(shell $(strip \
	$(ECHO) $(ECHOFLAGS) \
		$(ROOT_GENERATED_HTML) | \
	$(SED) $(SEDFLAGS) \
		-e 's/(.*\/)(.*\/)/\2/;' \
			-; \
	))
BACK_TO_DOC                   := $(shell $(strip \
	$(ECHO) $(ECHOFLAGS) \
		$(ROOT_GENERATED_DOCUMENTATION)$(HTML_OUTPUT) | \
	$(SED) $(SEDFLAGS) \
		-e 's#[^/]##g;' \
		-e 's#\/#\.\.\/#g;' \
			-; \
	))

# Built-in Special Targets
#~ .SECONDARY :                  # Uncomment for debugging.
.PHONY : \
	all \
	doxygen-version \
	templates-html \
	documentation-html \
	hardware \
	clean-hardware \
	mostlyclean clean-html clean \
	help hello

# Targets
#   Generate the complete documentation.
all : hello templates-html documentation-html

#   Query doxygen binary.
doxygen-version :
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(DOXYGEN) $(DOXYGENFLAGS) \
		--version;

#   Generate doxygen’s html templates: header, footer, stylesheet
templates-html :
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(DOXYGEN) $(DOXYGENFLAGS) \
		-w html \
		$(HTML_HEADER) \
		$(HTML_FOOTER) \
		$(HTML_STYLESHEET);

#   Target Hook for html documentation.
documentation-html : $(INDEX_HTML)
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	@$(ECHO) $(ECHOFLAGS) \
		"\nWith your favorite browser, now open:"\
		"\n  file://$${PWD}/$(<)"\
		"\n";

#   Add reference to favicon in header.
$(HTML_HEADER_ICON) : $(HTML_HEADER) $(FAVICON)
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Set a reference to “$(FAVICON)” in “$(@)” $(M5)$(M5)";
	$(SED) $(SEDFLAGS) \
		-e "s#<head>#&\n<link rel=\"icon\" type=\"image\/png\" href=\"$(BACK_TO_DOC)$(FAVICON)\"\/>#;" \
			$(<) > $(@);

#   Use current doxygen version and update newly created Doxyfile.
$(DOXYFILE) : $(DOXYORIG)
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Update the Doxyfile via “doxygen $(DOXYGEN_VERSION)” $(M5)$(M5)";
	$(SED) $(SEDFLAGS) \
		-e "s#(^PROJECT_LOGO.*\=)(.*)#\1$(PROJECT_LOGO)#g;" \
		-e "s#(^PROJECT_BRIEF.*\=)(.*)#\1$(PROJECT_BRIEF)#g;" \
		-e "s#(^PROJECT_NUMBER.*\=)(.*)#\1\"$(PROJECT_NUMBER)\"#g;" \
		-e "s#(^USE_MDFILE_AS_MAINPAGE.*\=)(.*)#\1$(MAINPAGE)#g;" \
		-e "s#(^INPUT[ \t]*\=)(.*)#\1 $(ROOT_GENERATED_FILES) \2#g;" \
		-e "s#(^IMAGE_PATH[ \t]*\=)(.*)#\1 $(ROOT_GENERATED_IMAGES) \2#g;" \
		-e "s#(^HTML_HEADER.*\=)(.*)#\1$(HTML_HEADER_ICON)#g;" \
		-e "s#(^HTML_FOOTER.*\=)(.*)#\1$(HTML_FOOTER)#g;" \
		-e "s#(^HTML_STYLESHEET.*\=)(.*)#\1$(HTML_STYLESHEET)#g;" \
		-e "s#(^HTML_EXTRA_STYLESHEET.*\=)(.*)#\1$(HTML_EXTRA_STYLESHEET)#g;" \
		-e "s#(^OUTPUT_DIRECTORY.*\=)(.*)#\1$(ROOT_GENERATED_DOCUMENTATION)#g;" \
		-e "s#(^HTML_OUTPUT.*\=)(.*)#\1$(HTML_OUTPUT)#g;" \
		-e "s#(^WARN_LOGFILE.*\=)(.*)#\1$(WARN_LOGFILE)#g;" \
			$(<) > $(@);
	$(DOXYGEN) $(DOXYGENFLAGS) \
		-u \
			$@;

#   Generate the html documentation.
$(INDEX_HTML) : $(MAINPAGE) \
	$(PROJECT_LOGO) \
	$(HTML_HEADER_ICON) \
	$(HTML_FOOTER) \
	$(HTML_STYLESHEET) \
	$(HTML_EXTRA_STYLESHEET) \
	$(ROOT_GENERATED_IMAGES)board.sch.png \
	$(ROOT_GENERATED_IMAGES)cables.sch.png \
	$(ROOT_GENERATED_IMAGES)board.pcb.png \
	$(ROOT_GENERATED_IMAGES)front-label.svg.png \
	$(ROOT_GENERATED_FILES)front-label.svg.pdf \
	$(BOM_MD_CABLES) \
	$(BOM_MD_BOARD) \
	$(DOXYFILE) ;
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Generate the html documentation via “doxygen $(DOXYGEN_VERSION)” in “$(ROOT_GENERATED_HTML)” $(M5)$(M5)";
	$(DOXYGEN) $(DOXYGENFLAGS) \
		$(DOXYFILE);

#   Create file folder.
$(ROOT_GENERATED_FILES) :
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(MKDIR) $(MKDIRFLAGS) \
		$(ROOT_GENERATED_FILES);

#   Create image folder.
$(ROOT_GENERATED_IMAGES) :
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(MKDIR) $(MKDIRFLAGS) \
		$(ROOT_GENERATED_IMAGES);

#   Generate image.
$(ROOT_HARDWARE_GSCHEM)board.sch.png : hardware
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";

#   Generate image.
$(ROOT_HARDWARE_GSCHEM)cables.sch.png : hardware
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";

#   Generate image.
$(ROOT_HARDWARE_PCB)board.pcb.png : hardware
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";

#   Generate image.
$(ROOT_HARDWARE_ARTWORK)front-label.svg.png : hardware
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";

#   Generate PDF.
$(ROOT_HARDWARE_ARTWORK)front-label.svg.pdf : hardware
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";

#   Copy generated image to image folder (used by website).
$(ROOT_GENERATED_IMAGES)board.sch.png : $(ROOT_HARDWARE_GSCHEM)board.sch.png $(ROOT_GENERATED_IMAGES)
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(CP) $(CPFLAGS) \
		$< $@ && \
	$(ECHO) $(ECHOFLAGS) \
		"Image $< copied to: $@";

#   Copy generated image to image folder (used by website).
$(ROOT_GENERATED_IMAGES)cables.sch.png : $(ROOT_HARDWARE_GSCHEM)cables.sch.png $(ROOT_GENERATED_IMAGES)
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(CP) $(CPFLAGS) \
		$< $@ && \
	$(ECHO) $(ECHOFLAGS) \
		"Image $< copied to: $@";

#   Copy generated image to image folder (used by website).
$(ROOT_GENERATED_IMAGES)board.pcb.png : $(ROOT_HARDWARE_PCB)board.pcb.png $(ROOT_GENERATED_IMAGES)
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(CP) $(CPFLAGS) \
		$< $@ && \
	$(ECHO) $(ECHOFLAGS) \
		"Image $< copied to: $@";

#   Copy generated image to image folder (used by website).
$(ROOT_GENERATED_IMAGES)front-label.svg.png : $(ROOT_HARDWARE_ARTWORK)front-label.svg.png $(ROOT_GENERATED_IMAGES)
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(CP) $(CPFLAGS) \
		$< $@ && \
	$(ECHO) $(ECHOFLAGS) \
		"Image $< copied to: $@";

#   Copy generated image to image folder (used by website).
$(ROOT_GENERATED_FILES)front-label.svg.pdf : $(ROOT_HARDWARE_ARTWORK)front-label.svg.pdf $(ROOT_GENERATED_FILES)
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(CP) $(CPFLAGS) \
		$< $@ && \
	$(ECHO) $(ECHOFLAGS) \
		"File $< copied to: $@";

#   Generate bom file (BoM = Bill of Material).
$(ROOT_HARDWARE_GSCHEM)board.bom.md : hardware
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";

#   Generate bom file (BoM = Bill of Material).
$(ROOT_HARDWARE_GSCHEM)cables.bom.md : hardware
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";

#   Copy generated bom file (BoM = Bill of Material).
$(BOM_MD_BOARD) : $(ROOT_HARDWARE_GSCHEM)board.bom.md
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(CP) $(CPFLAGS) \
		$< $@ && \
	$(ECHO) $(ECHOFLAGS) \
		"File $< copied to: $@";

#   Copy generated bom file (BoM = Bill of Material).
$(BOM_MD_CABLES) : $(ROOT_HARDWARE_GSCHEM)cables.bom.md
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(CP) $(CPFLAGS) \
		$< $@ && \
	$(ECHO) $(ECHOFLAGS) \
		"File $< copied to: $@";

#   Call hardware Makefile to generate images and markdown files.
hardware :
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(MAKE) \
		-C $(ROOT_HARDWARE) \
			images markdown label;

#   Clean hardware documentation.
clean-hardware :
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	$(MAKE) \
		-C $(ROOT_HARDWARE) \
			clean;

#   Clean generated files, templates and log file.
mostlyclean : clean-hardware
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	-$(RM) $(RMFLAGS) \
		$(HTML_HEADER_ICON) \
		$(HTML_HEADER).bak \
		$(HTML_HEADER) \
		$(HTML_FOOTER).bak \
		$(HTML_FOOTER) \
		$(HTML_STYLESHEET).bak \
		$(HTML_STYLESHEET) \
		$(DOXYFILE).bak \
		$(DOXYFILE);
	-$(RM) $(RMFLAGS) \
		$(WARN_LOGFILE);

#   Clean html output.
clean-html :
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	-$(RM) $(RMFLAGS) \
		-r \
			$(ROOT_GENERATED_HTML);

#   Clean output folders.
clean : hello mostlyclean clean-html
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	-$(RM) $(RMFLAGS) \
		-r \
			$(BOM_MD_BOARD) \
			$(BOM_MD_CABLES) \
			$(ROOT_GENERATED_IMAGES) \
			$(ROOT_GENERATED_FILES) \
			$(ROOT_GENERATED_DOCUMENTATION);

#   Provide Help Information
help : hello
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5) Process target “$@” $(M5)$(M5)";
	@$(ECHO) $(ECHOFLAGS) \
		"\nall$(TAB2)– Generate the complete documentation."\
		"\ndoxygen-version$(TAB2)– Query doxygen binary."\
		"\ntemplates-html$(TAB2)– Generate doxygen’s html templates: header, footer, stylesheet"\
		"\ndocumentation-html$(TAB2)– Target Hook for html documentation."\
		"\n..."\
		"\nhardware$(TAB2)– Call hardware Makefile to generate images and markdown files."\
		"\nclean-hardware$(TAB2)– Clean hardware documentation."\
		"\n..."\
		"\nmostlyclean$(TAB2)– Clean templates and log file."\
		"\nclean-html$(TAB2)– Clean html output."\
		"\nclean$(TAB2)– Clean output."\
		"\nhello$(TAB2)– greeter, provided with all, clean and help"\
		"\nhelp$(TAB2)– provide this help information"\
		"\n";

# Say hello.
#   provided with all, clean and help
hello :
	@$(ECHO) $(ECHOFLAGS) \
		"\n$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)"\
		"\n$(M5) Zerocat Chipflasher – The Documentation"\
		"\n$(M5) This Makefile builds/cleans the Documentation."\
		"\n$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)$(M5)";

##>! @endcond

Copyright

Zerocat Chipflasher — Flash free firmware to BIOS chips, kick the Management Engine.

Copyright (C) 2016-2018, 2020, 2021 Kai Mertens kmx@p.nosp@m.oste.nosp@m.o.net
Copyright (C) 2016 rekado rekad.nosp@m.o@el.nosp@m.ephly.nosp@m..net

The Zerocat Chipflasher is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The Zerocat Chipflasher is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

This file is part of the Zerocat Chipflasher.

“In file” Documentation

Usage

$ make help