l4/mk/doc.mk

   1 # -*- Makefile -*-
   2 #
   3 # DROPS (Dresden Realtime OPerating System) Component
   4 #
   5 # Makefile-Template for doc directories
   6 #
   7 # install.inc is used, see there for further documentation
   8
   9 ifeq ($(origin _L4DIR_MK_DOC_MK),undefined)
  10 _L4DIR_MK_DOC_MK=y
  11
  12 ROLE = doc.mk
  13
  14 include $(L4DIR)/mk/Makeconf
  15 $(GENERAL_D_LOC): $(L4DIR)/mk/doc.mk
  16
  17 ifeq ($(IN_OBJ_DIR),)
  18 ##################################################################
  19 #
  20 # Empty IN_OBJ_DIR means we are in the source directory and have
  21 # to first generate a Makefile in the build-dir.
  22 #
  23 ##################################################################
  24
  25 all install clean cleanall help:: $(OBJ_DIR)/Makefile.build
  26         $(VERBOSE)PWD=$(OBJ_DIR) $(MAKE) -C $(OBJ_DIR) O=$(OBJ_BASE) -f Makefile.build $@
  27
  28
  29 $(OBJ_DIR)/Makefile.build: $(SRC_DIR)/Makefile
  30         $(VERBOSE)install -d $(dir $@)
  31         $(VERBOSE)echo 'IN_OBJ_DIR=1'                 > $@
  32         $(VERBOSE)echo 'L4DIR=$(L4DIR_ABS)'          >> $@
  33         $(VERBOSE)echo 'SRC_DIR=$(SRC_DIR)'          >> $@
  34         $(VERBOSE)echo 'OBJ_BASE=$(OBJ_BASE)'        >> $@
  35         $(VERBOSE)echo 'PKGDIR_ABS=$(PKGDIR_ABS)'    >> $@
  36         $(VERBOSE)echo 'vpath %.fig $(SRC_DIR)'      >> $@
  37         $(VERBOSE)echo 'vpath %.tex $(SRC_DIR)'      >> $@
  38         $(VERBOSE)echo 'include $(SRC_DIR)/Makefile' >> $@
  39
  40 else
  41 ###################################################################
  42 #
  43 # We are in the build directory and can process the documentation
  44 #
  45 ###################################################################
  46
  47 # default is to install all targets
  48 INSTALL_TARGET_MASK ?= %
  49
  50 ifneq ($(TARGET),)
  51 # if no SRC_DOX is given, but TARGET, extract it from TARGET
  52 ifeq ($(origin SRC_DOX),undefined)
  53 SRC_DOX            := $(filter $(addsuffix .cfg, $(TARGET)),$(wildcard *.cfg))
  54 ifneq ($(SRC_DOX),)
  55 $(error SRC_DOX is undefined, but TARGET is defined. This is invalid since 04/23/2003)
  56 endif
  57 endif
  58 # the same for SRC_TEX
  59 ifeq ($(origin SRC_TEX),undefined)
  60 SRC_TEX            := $(filter $(TARGET:.ps=.tex),$(wildcard *.tex)) \
  61                       $(filter $(TARGET:.pdf=.tex),$(wildcard *.tex))
  62                       $(filter $(TARGET:.dvi=.tex),$(wildcard *.tex))
  63 ifneq ($(SRC_TEX),)
  64 $(error SRC_TEX is undefined, but TARGET is defined. This is invalid since 04/23/2003)
  65 endif
  66 endif
  67 endif
  68
  69 TARGET_DOX      = $(SRC_DOX:.cfg=) $(SRC_DOX_REF:.cfg=) \
  70                   $(SRC_DOX_GUIDE:.cfg=) $(SRC_DOX_INT:.cfg=)
  71 INSTALL_TARGET_DOX ?= $(filter $(INSTALL_TARGET_MASK), $(TARGET_DOX))
  72 TARGET_TEX      ?= $(SRC_TEX:.tex=.ps) $(SRC_TEX:.tex=.pdf)
  73 DEPS            += $(foreach x,$(SRC_TEX:.tex=.dvi),$(dir $x).$(notdir $x).d)
  74
  75 # if no TARGET is given, generate it from all types of targets
  76 TARGET          ?= $(TARGET_DOX) $(TARGET_TEX)
  77 DEPS            += $(foreach file,$(TARGET),$(dir $(file)).$(notdir $(file)).d)
  78
  79 all:: $(TARGET)
  80 $(TARGET): $(OBJ_DIR)/.general.d
  81
  82 ####################################################################
  83 #
  84 # Doxygen specific
  85 #
  86 ####################################################################
  87 DOXY_FLAGS += $(DOXY_FLAGS_$@)
  88
  89 OUTPUTDIR = $(shell perl -n -e '/^\s*OUTPUT_DIRECTORY\s*=\s*(\S+)/ && print "$$1\n"' $(1))
  90
  91 # we refer to %/html sometimes. However, make fails on a rule of the form
  92 # "% %/html:%.cfg", thus the workaround (others than static-pattern-rules
  93 # won't work)
  94 $(addprefix $(OBJ_DIR)/,$(addsuffix /html,$(TARGET_DOX))):$(OBJ_DIR)/%/html:$(OBJ_DIR)/%
  95
  96 # We can give an internal rule for doxygen, as the directory specified
  97 # in the config-file should be the name of the config file with the
  98 # .cfg removed.
  99 # Use make DOXY_FAST=y to just build the HTML without graphics
 100 # Use make DOXY_FULL=y to build HTMl with graphics and the PDF
 101 # $(VERBOSE)$(ECHO) ENABLED_SECTIONS=WORKING_SUBPAGES >> $@.flags
 102 $(OBJ_DIR)/% $(OBJ_DIR)/%/html:$(SRC_DIR)/%.cfg
 103         #generate the flags-file
 104         $(VERBOSE)$(MKDIR) $@
 105         $(VERBOSE)$(ECHO) '@INCLUDE_PATH=/'                                 > $@.flags
 106         $(VERBOSE)$(ECHO) '@INCLUDE=$(SRC_DIR)/$(notdir $<)'               >> $@.flags
 107         $(VERBOSE)$(ECHO) $(DOXY_FLAGS)                                    >> $@.flags
 108         $(VERBOSE)$(ECHO) OUTPUT_DIRECTORY=$(OBJ_DIR)/$(call OUTPUTDIR,$<) >> $@.flags
 109         $(VERBOSE)if [ -n "$(DOXY_FAST)" ]; then $(ECHO) HAVE_DOT=NO;  $(ECHO) GENERATE_LATEX=NO;  fi   >> $@.flags
 110         $(VERBOSE)if [ -n "$(DOXY_FULL)" ]; then $(ECHO) HAVE_DOT=YES; $(ECHO) GENERATE_LATEX=YES; fi   >> $@.flags
 111         $(VERBOSE)if [ -n "$(DOXY_RELEASE)" ]; then \
 112                     $(ECHO) HAVE_DOT=YES; \
 113                     $(ECHO) GENERATE_LATEX=YES; \
 114                     $(ECHO) SHOW_FILES=NO; \
 115                     $(ECHO) SHOW_DIRECTORIES=NO; \
 116                     $(ECHO) INTERNAL_DOCS=NO; \
 117                     $(ECHO) GENERATE_TODOLIST=NO; \
 118                     $(ECHO) GENERATE_TESTLIST=NO; \
 119                     $(ECHO) GENERATE_BUGLIST=NO; \
 120                     $(ECHO) HIDE_UNDOC_CLASSES=YES; \
 121                     $(ECHO) HIDE_UNDOC_MEMBERS=YES; \
 122                   fi   >> $@.flags
 123         $(VERBOSE)cd $(L4DIR)/pkg && \
 124           for f in $(addsuffix /doc/files.cfg,*); \
 125             do echo '@INCLUDE = $$(L4DIR)/pkg/'$$f; done >> $@.flags
 126         $(VERBOSE)cd $(OBJ_BASE)/include && $(call MAKEDEP,doxygen) L4DIR=$(L4DIR) $(DOXYGEN) $@.flags
 127         $(VERBOSE)for file in $(ADD_FILES_TO_HTML); do cp $$file $@/html; done
 128         $(VERBOSE)( [ -r $@/latex/Makefile ] && \
 129            echo | PWD=$@/latex $(MAKE) -C $@/latex ) || true
 130         $(VERBOSE)if [ -d $@ ] ; then touch $@ ; fi
 131
 132 # Installation rules follow
 133 #
 134 # define LOCAL_INSTALLDIR prior to including install.inc, where the install-
 135 # rules are defined. Same for INSTALLDIR.
 136 INSTALLDIR_HTML         ?= $(DROPS_STDDIR)/doc/html
 137 INSTALLFILE_HTML        ?= $(CP) -pR $(1) $(2)
 138 INSTALLDIR_HTML_LOCAL   ?= $(OBJ_BASE)/doc/html
 139 INSTALLFILE_HTML_LOCAL  ?= $(if $(call is_dir,$(2)), \
 140                               find '$(dir $(1))' -name '$(notdir $(1))' | xargs $(LN) -t $(2) -sf, \
 141                               find '$(dir $(1))' -name '$(notdir $(1))' | xargs -I '{}' $(LN) -sf '{}' $(2))
 142
 143 INSTALLDIR              = $(INSTALLDIR_HTML)
 144 INSTALLFILE             = $(INSTALLFILE_HTML)
 145 INSTALLDIR_LOCAL        = $(INSTALLDIR_HTML_LOCAL)
 146 INSTALLFILE_LOCAL       = $(INSTALLFILE_HTML_LOCAL)
 147
 148 all::   $(TARGET) \
 149         $(addprefix $(INSTALLDIR_LOCAL)/, $(addsuffix .title, $(INSTALL_TARGET_DOX)))
 150
 151 $(OBJ_DIR)/$(SRC_DOX_REF:.cfg=.title): BID_DOC_DOXTYPE=ref
 152 $(OBJ_DIR)/$(SRC_DOX_GUIDE:.cfg=.title): BID_DOC_DOXTYPE=guide
 153 $(OBJ_DIR)/$(SRC_DOX_INT:.cfg=.title): BID_DOC_DOXTYPE=int
 154
 155 # first line: type
 156 # second line: title that will appear at the generated index page
 157 $(OBJ_DIR)/%.title:$(SRC_DIR)/%.cfg $(OBJ_DIR)/.general.d
 158         $(VERBOSE)$(ECHO) $(BID_DOC_DOXTYPE)>$@
 159         $(VERBOSE)MAKEFLAGS= $(MAKE) -s -f $(L4DIR)/mk/makehelpers.inc -f $< \
 160            BID_print VAR=PROJECT_NAME >>$@
 161
 162 # Install the title file locally
 163 # The installed title file depends on the installed doku for message reasons
 164 $(foreach f,$(INSTALL_TARGET_DOX),$(INSTALLDIR_LOCAL)/$(f).title):$(INSTALLDIR_LOCAL)/%.title:$(OBJ_DIR)/%.title $(INSTALLDIR_LOCAL)/%
 165         $(VERBOSE)$(call INSTALLFILE_LOCAL,$<,$@)
 166         @$(call UPDATE_HTML_MESSAGE,$(INSTALLDIR_LOCAL))
 167
 168 # Install the docu locally, the title file will depend on
 169 $(foreach f,$(INSTALL_TARGET_DOX),$(INSTALLDIR_LOCAL)/$(f)):$(INSTALLDIR_LOCAL)/%:$(OBJ_DIR)/% $(OBJ_DIR)/%/html
 170         @$(INSTALL_DOC_LOCAL_MESSAGE)
 171         $(VERBOSE)$(INSTALL) -d $@
 172         $(VERBOSE)$(call INSTALLFILE_LOCAL,$</html/*,$@)
 173
 174 # Install the title file globally
 175 # The installed title file depends on the installed doku for message reasons
 176 $(foreach f,$(INSTALL_TARGET_DOX),$(INSTALLDIR)/$(f).title):$(INSTALLDIR)/%.title:$(OBJ_DIR)/%.title $(INSTALLDIR)/%
 177         $(VERBOSE)$(call INSTALLFILE,$<,$@)
 178         @$(call UPDATE_HTML_MESSAGE,$(INSTALLDIR))
 179
 180 # Install the docu globally, the title file will depend on
 181 $(foreach f,$(INSTALL_TARGET_DOX),$(INSTALLDIR)/$(f)):$(INSTALLDIR)/%:$(OBJ_DIR)/% $(OBJ_DIR)/%/html
 182         @$(INSTALL_DOC_MESSAGE)
 183         $(if $(INSTALLFILE),$(VERBOSE)$(INSTALL) -d $@)
 184         $(VERBOSE)$(call INSTALLFILE,$</html/*,$@)
 185
 186 install:: $(addprefix $(INSTALLDIR)/,$(addsuffix .title,$(INSTALL_TARGET_DOX)))
 187 .PHONY: $(addprefix $(INSTALLDIR)/,$(INSTALL_TARGET_DOX) \
 188                                    $(addsuffix .title,$(INSTALL_TARGET_DOX)))
 189
 190
 191 #################################################################
 192 #
 193 # Latex specific
 194 #
 195 #################################################################
 196
 197 FIG2EPS_PROG ?= fig2dev -L eps
 198 FIG2PDF_PROG ?= fig2dev -L pdf
 199 FIG2PNG_PROG ?= fig2dev -L png
 200
 201 $(SRC_TEX:.tex=.dvi) $(TARGET): $(SRC_FIG:.fig=.pdf) $(SRC_FIG:.fig=.png) $(SRC_FIG:.fig=.eps)
 202
 203 %.eps: %.fig $(OBJ_DIR)/.general.d
 204         @$(GEN_MESSAGE)
 205         $(VERBOSE)$(FIG2EPS_PROG) $< $@
 206
 207 %.pdf: %.fig $(OBJ_DIR)/.general.d
 208         @$(GEN_MESSAGE)
 209         $(VERBOSE)$(FIG2PDF_PROG) $< $@
 210
 211 %.png: %.fig $(OBJ_DIR)/.general.d
 212         @$(GEN_MESSAGE)
 213         $(VERBOSE)$(FIG2PNG_PROG) $< $@
 214
 215 %.ps: %.dvi $(OBJ_DIR)/.general.d
 216         @$(GEN_MESSAGE)
 217         $(VERBOSE)$(call MAKEDEP,dvips) dvips -o $@ $<
 218         $(VERBOSE)$(VIEWERREFRESH_PS)
 219
 220 %.pdf: %.tex $(OBJ_DIR)/.general.d
 221         @$(GEN_MESSAGE)
 222         $(VERBOSE)$(PDFLATEX) $< || \
 223                 (($(GREP) 'TeX capacity exceeded' $*.log && \
 224                 echo -e "\n\033[31mIncrease pool_size to 200000 in" \
 225                 "/etc/texmf/texmf.cnf!\033[m\n" && false) || false)
 226         $(VERBOSE)$(GREP) '\citation' $*.aux && \
 227                 bibtex $* || true
 228         $(VERBOSE)(export size=1; touch $@; \
 229                 until [ $$size -eq `ls -o $@ | awk '{print $$4}'` ]; do\
 230                   export size=`ls -o $@ | awk '{print $$4}'` ;\
 231                   $(PDFLATEX) $< ;\
 232                 done)
 233 # one more time, just to be sure ...
 234         $(VERBOSE)$(PDFLATEX) $<
 235
 236 %.dvi: %.tex $(OBJ_DIR)/.general.d
 237         @$(GEN_MESSAGE)
 238         $(VERBOSE)$(call MAKEDEP,$(LATEX)) $(LATEX) $<
 239         $(VERBOSE)if grep -q '\indexentry' $*.idx; then makeindex $*; fi
 240         $(VERBOSE)if grep -q '\citation' $*.aux; then bibtex $*; fi
 241         # Do we really need to call latex unconditionally again? Isn't it
 242         # sufficient to check the logfile for the "rerun" text?
 243         $(VERBOSE)$(LATEX) $<
 244         $(VERBOSE)latex_count=5 ; \
 245         while egrep -s 'Rerun (LaTeX|to get cross-references right)' $*.log &&\
 246                 [ $$latex_count -gt 0 ] ; do \
 247                 $(LATEX) $< \
 248                 let latex_count=$$latex_count-1 ;\
 249         done
 250         $(VERBOSE)$(VIEWERREFRESH_DVI)
 251
 252 SHOWTEX ?= $(firstword $(SRC_TEX))
 253 SHOWDVI ?= $(SHOWTEX:.tex=.dvi)
 254 SHOWPS  ?= $(SHOWTEX:.tex=.ps)
 255 SHOWPDF ?= $(SHOWTEX:.tex=.pdf)
 256
 257 VIEWER_DVI        ?= xdvi
 258 VIEWER_PS         ?= gv
 259 VIEWER_PDF        ?= xpdf
 260 VIEWERREFRESH_DVI ?= killall -USR1 xdvi xdvi.bin xdvi.real || true
 261 VIEWERREFRESH_PS  ?= killall -HUP $(VIEWER_PS) || true
 262
 263 dvi:    $(SHOWDVI)
 264 show showdvi: dvi
 265         $(VERBOSE)$(VIEWER_DVI) $(SHOWDVI) &
 266
 267 ps:     $(SHOWPS)
 268 showps: ps
 269         $(VERBOSE)$(VIEWER_PS) $(SHOWPS) &
 270
 271 pdf:    $(SHOWPDF)
 272 showpdf: pdf
 273         $(VERBOSE)$(VIEWER_PDF) $(SHOWPDF) &
 274
 275 clean::
 276         $(VERBOSE)$(RM) $(addprefix $(OBJ_DIR)/, \
 277                 $(addsuffix .title,$(TARGET_DOX)))
 278         $(VERBOSE)$(RM) $(addprefix $(OBJ_DIR)/, \
 279                 $(addsuffix .flags,$(TARGET_DOX)))
 280         $(VERBOSE)$(RM) $(wildcard $(addprefix $(OBJ_DIR)/, $(foreach ext, \
 281                 aux bbl blg dvi idx ilg ind log lod ltf toc out, \
 282                 $(SRC_TEX:.tex=.$(ext))) texput.log ))
 283
 284 cleanall:: clean
 285         $(VERBOSE)$(RM) -r $(wildcard $(addprefix $(OBJ_DIR)/, \
 286                 $(TARGET)) $(wildcard .*.d))
 287         $(VERBOSE)$(RM) $(wildcard $(addprefix $(OBJ_DIR)/, \
 288                 $(SRC_TEX:.tex=.ps) $(SRC_TEX:.tex=.pdf)))
 289         $(VERBOSE)$(RM) $(wildcard $(addprefix $(OBJ_DIR)/, \
 290                 $(SRC_FIG:.fig=.eps) $(SRC_FIG:.fig=.pdf) $(SRC_FIG:.fig=.png)))
 291         $(VERBOSE)$(RM) $(wildcard $(addprefix $(OBJ_DIR)/, \
 292                 Makefile Makefile.build))
 293
 294 .PHONY: all clean cleanall config help install oldconfig txtconfig
 295 .PHONY: ps pdf dvi showps showpdf showdvi show
 296
 297 help::
 298         @echo "Specify a target:"
 299         @echo "all       - generate documentation and install locally"
 300 ifneq (,$(INSTALL_TARGET_DOX))
 301         @echo "install   - generate documentation and install globally"
 302 endif
 303         @echo "dvi       - compile the primary TeX file into dvi"
 304         @echo "showdvi   - invoke the dvi viewer on the primary TeX file"
 305         @echo "ps        - compile the primary TeX file into ps"
 306         @echo "showps    - invoke the ps viewer on the primary TeX file"
 307         @echo "pdf       - compile the primary TeX file into pdf"
 308         @echo "showpdf   - invoke the pdf viewer on the primary TeX file"
 309         @echo "clean     - delete generated intermediate files"
 310         @echo "cleanall  - delete all generated files"
 311         @echo "help      - this help"
 312         @echo
 313 ifneq (,$(SRC_TEX))
 314         @echo "Primary TeX file: $(SHOWTEX)"
 315         @echo "Other documentation to be built: $(filter-out $(SHOWPDF) $(SHOWPS) $(SHOWDVI),$(TARGET))"
 316 else
 317 ifneq (,$(TARGET_DOX))
 318         @echo "Primary Doxygen file: $(addsuffix .cfg, $(TARGET_DOX))"
 319 endif
 320         @echo "Documentation to be built: $(TARGET)"
 321 endif
 322
 323 -include $(DEPSVAR)
 324
 325 endif   # IN_OBJ_DIR
 326
 327 endif   # _L4DIR_MK_DOC_MK undefined