Newer
Older
Handbook / makefile-templates / Makefile.handbook
  1. ################################################################################
  2. #
  3. # Makefile for DBCOURSES handbooks. Revamped completely from old
  4. # monolithic version to a "many-makefiles" model. Each major sub-unit of
  5. # the handbook has its own makefile, and is called recursively from here.
  6. # This makes management of the whole process a bit more complex, but a lot
  7. # more flexible. It's now possible, for example, to build many of the
  8. # files for a single tutorial by going into that tutorial's directory and
  9. # running a make there. The old scheme was also wont to rebuild lots of
  10. # extraneous stuff when only one file changed (especially with graphics).
  11. # This does not appear to be (and should not) be a problem with the new
  12. # scheme.
  13. #
  14. ################################################################################
  15.  
  16.  
  17. SHELL=/bin/sh
  18.  
  19.  
  20. ################################################################################
  21. #
  22. # Given that we print out our own messages, I see no point in splurging
  23. # "Entering...leaving directory" messages all over the screen. It's hard
  24. # enough to figure out what's going on already :)
  25. #
  26. MAKEFLAGS=--no-print-directory
  27.  
  28.  
  29. ################################################################################
  30. #
  31. # Required Environment Variables
  32. #
  33. # TEACHING_SHARED
  34. # This variable specifies the path to the top level of the teaching
  35. # shared directory hierarchy (e.g., /path/to/Teaching/Shared).
  36. #
  37. TEACHING_SHARED?=$(error The required environment variable TEACHING_SHARED has not been defined. It should point to the root level of the shared teaching directory (e.g., /path/to/Teaching/Shared))
  38. #
  39. # ALL_PAPERS_ROOT
  40. # This variable specifies the path to the top level directory for all
  41. # papers taught, i.e., the directory that contains the individual paper
  42. # directory hierarchies. For example, /path/to/Teaching/2005.
  43. #
  44. ALL_PAPERS_ROOT?=$(error The required environment variable ALL_PAPERS_ROOT has not been defined. It should point to the root level of the current teaching directory hierarchy (e.g., /path/to/Teaching/2005))
  45. #
  46. # HANDBOOK_INSTALL_ROOT
  47. # This variable specifies the path to the top level directory on the web
  48. # server, under which the files for this paper will be installed (that is,
  49. # the directory that contains the individual paper directory hierarchies).
  50. # For example, \\INFO-NTS-12\DBCourses$ (this may require munging).
  51. #
  52. HANDBOOK_INSTALL_ROOT?=$(error The required environment variable HANDBOOK_INSTALL_ROOT has not been defined. It should point to the root level of the directory hierarchy on the web server (e.g., \\INFO-NTS-12\DBCourses$))
  53.  
  54.  
  55. ################################################################################
  56. #
  57. # Set up paths to makefile include directories.
  58. #
  59. # GLOBAL_HANDBOOK_INCLUDE is the global include directory in the "Shared"
  60. # hierarchy, and is defined relative to the root of that hierarchy.
  61. #
  62. # LOCAL_HANDBOOK_INCLUDE is the local include directory for this
  63. # particular paper, and is defined relative to the current execution
  64. # directory. We are assuming a fixed directory structure here! We can't
  65. # really do this as an environment variable because the full path will be
  66. # different for each paper, and we can't use the variables from
  67. # paper_variables.make to set the path, because that file is in the
  68. # include directory! <head spins> We will, however, allow for the
  69. # possibility of someone wanting to define this as an environment variable
  70. # by making it a conditional assignment.
  71. #
  72. GLOBAL_HANDBOOK_INCLUDE?=$(TEACHING_SHARED)/Authoring/Handbook/make-includes
  73.  
  74. export LOCAL_HANDBOOK_INCLUDE?=$(shell pwd)/make-includes
  75.  
  76.  
  77. ################################################################################
  78. #
  79. # Include local system-specific configuration.
  80. #
  81. include $(GLOBAL_HANDBOOK_INCLUDE)/local_configuration.make
  82.  
  83.  
  84. ################################################################################
  85. #
  86. # Include standard make environment variables.
  87. #
  88. include $(GLOBAL_HANDBOOK_INCLUDE)/standard_environment.make
  89.  
  90.  
  91. ################################################################################
  92. #
  93. # Include variables defining the current paper.
  94. #
  95. include $(LOCAL_HANDBOOK_INCLUDE)/paper_variables.make
  96.  
  97.  
  98. ################################################################################
  99. #
  100. # Directories for the major sections. Add to as necessary. Sections should
  101. # be listed in the order that they will appear in the handbook. Remember to
  102. # exclude CVS directories (doh!).
  103. #
  104. SECTION_DIRS:=$(shell $(FIND) sections -mindepth 1 -maxdepth 1 -type d -not -name CVS)
  105.  
  106.  
  107. ################################################################################
  108. #
  109. # Run one-time initialisation stuff.
  110. #
  111. # Ensure that the patterns files exist. If they don't, copy the originals
  112. # across from the shared directory and abort the run so that the user can
  113. # edit them appropriately.
  114. #
  115. CHECK_ANSWERS_PATTERNS:=$(shell ($(TEST) -f $(LOCAL_HANDBOOK_INCLUDE)/answers.patterns) || ($(CP) $(TEACHING_SHARED)/Authoring/Handbook/makefile-templates/answers.patterns $(LOCAL_HANDBOOK_INCLUDE); $(ECHO) "answers"))
  116. CHECK_QUESTIONS_PATTERNS:=$(shell ($(TEST) -f $(LOCAL_HANDBOOK_INCLUDE)/questions.patterns) || ($(CP) $(TEACHING_SHARED)/Authoring/Handbook/makefile-templates/questions.patterns $(LOCAL_HANDBOOK_INCLUDE); $(ECHO) "questions"))
  117. CHECK_INSTALL_PATTERNS:=$(shell ($(TEST) -f $(LOCAL_HANDBOOK_INCLUDE)/install.patterns) || ($(CP) $(TEACHING_SHARED)/Authoring/Handbook/makefile-templates/install.patterns $(LOCAL_HANDBOOK_INCLUDE); $(ECHO) "install"))
  118. CHECK_ALL_PATTERNS:=$(CHECK_ANSWERS_PATTERNS) $(CHECK_QUESTIONS_PATTERNS) $(CHECK_INSTALL_PATTERNS)
  119.  
  120. ifneq "$(strip $(CHECK_ALL_PATTERNS))" ""
  121. $(error Patterns files have been restored from defaults ($(CHECK_ALL_PATTERNS)), please check them before continuing)
  122. endif
  123. #
  124. # Delete the marker file that indicates that we've already initialised the
  125. # sub-sections by removing their "content checked" marker files. There's
  126. # only one of these, so it's much easier to deal with :)
  127. #
  128. # Note: NOINIT should _not_ be exported to this sub-make, to ensure that
  129. # the sub-makefile's one-time initialisation is executed.
  130. #
  131. CLEANUP_MARKER_FILES:=$(foreach d,$(SECTION_DIRS),$(shell $(MAKE) -C $d init-clean))
  132.  
  133.  
  134. ################################################################################
  135. #
  136. # Load in patterns for which items to install. In particular, we are looking
  137. # for the value "handbook_root" to appear in either QUESTION_INSTALL_PATTERNS
  138. # or ANSWER_INSTALL_PATTERNS. This tells us whether to install links for the
  139. # questions and answers versions of the handbook, respectively. Yes, this is
  140. # a hack!
  141. #
  142. # *_INSTALL_PATTERNS defines the patterns for installing on the web server.
  143. #
  144. QUESTION_INSTALL_PATTERNS:=
  145. ANSWER_INSTALL_PATTERNS:=
  146.  
  147. #
  148. # Load in the install patterns from the local make-includes directory.
  149. #
  150. include $(LOCAL_HANDBOOK_INCLUDE)/install.patterns
  151.  
  152.  
  153. ################################################################################
  154. #
  155. # Lists of LaTeX files to be \input into the master LaTeX document. Just
  156. # build a single list for everything; we can extract the sections we want
  157. # at the time using make's filter function, as the sections have distinct
  158. # names. These are statically defined rather than using a find command,
  159. # because the files may not exist at the time the find command is
  160. # executed. This Would Be Non-Useful.
  161. #
  162. QUESTION_TEX_INPUTS:=$(foreach d,$(SECTION_DIRS),$d/question-manifest.tex)
  163. ANSWER_TEX_INPUTS:=$(foreach d,$(SECTION_DIRS),$d/answer-manifest.tex)
  164.  
  165. LATEX_INCLUDES:=$(shell $(FIND) latex-includes -name "*.tex")
  166.  
  167.  
  168. ################################################################################
  169. #
  170. # Additional options for the coursehandbook document class to set up
  171. # the details of the paper. These get included in a call to the
  172. # \papersetup macro in the template file (including the options
  173. # directly into the \documentclass is problematic --- see
  174. # coursehandbook.cls for details). The values are set in
  175. # latex-includes/paper_variables.make.
  176. #
  177. PAPER_OPTIONS:=subjectcode=$(SUBJECT_CODE),papernumber=$(PAPER_NUMBER),papertitle=$(PAPER_TITLE),paperyear=$(PAPER_YEAR),paperperiod=$(PAPER_PERIOD),authors=$(HANDBOOK_AUTHORS)
  178.  
  179.  
  180. ################################################################################
  181. #
  182. # Directory to install files into on web server.
  183. #
  184. INSTALL_DIRECTORY:=$(HANDBOOK_INSTALL_ROOT)/$(SUBJECT_CODE)$(PAPER_NUMBER)/Handbook
  185.  
  186.  
  187. ################################################################################
  188. #
  189. # Files to be installed on web server.
  190. #
  191. QUESTION_INSTALL_FILES:=handbook.pdf handbook-2up.pdf $(wildcard *.png)
  192.  
  193. ANSWER_INSTALL_FILES:= handbook-answers.pdf handbook-answers-2up.pdf \
  194. $(wildcard *.png)
  195.  
  196. # Sorting gets rid of any duplicates (e.g., the PNG files).
  197. INSTALL_FILES:=$(sort $(QUESTION_INSTALL_FILES) $(ANSWER_INSTALL_FILES))
  198.  
  199.  
  200. ################################################################################
  201. #
  202. # Lists of files for cleaning up.
  203. #
  204. WEB_CLEAN_FILES:=*.png
  205. PRINT_CLEAN_FILES:=handbook.tex handbook-answers.tex \
  206. *.pdf *.ps *.dvi *.aux *.log *.toc *.idx *.ind *.tex~ *.out
  207. ALL_CLEAN_FILES:=$(WEB_CLEAN_FILES) $(PRINT_CLEAN_FILES)
  208.  
  209.  
  210. ################################################################################
  211. #
  212. # List of possible targets.
  213. #
  214. TARGETS:=all targets debug install \
  215. web web-questions web-answers \
  216. print print-questions print-answers \
  217. questions answers \
  218. section-questions section-answers \
  219. question-pdfs answer-pdfs \
  220. clean web-clean print-clean
  221.  
  222. .PHONY: $(TARGETS)
  223.  
  224.  
  225. ################################################################################
  226. #
  227. # Build everything.
  228. #
  229. all: web print
  230.  
  231.  
  232. ################################################################################
  233. #
  234. # Build questions/answers only.
  235. #
  236. questions: web-questions print-questions
  237.  
  238. answers: web-answers print-answers
  239.  
  240.  
  241. ################################################################################
  242. #
  243. # Build web version only. NOINIT and SECTION should be exported to all
  244. # these sub-makes.
  245. #
  246. web: general-graphics web-questions web-answers
  247.  
  248. web-questions:
  249. @$(foreach d,$(SECTION_DIRS),if $(MAKE) -C $d web-questions NOINIT=x SECTION=$(notdir $(d)); then $(TRUE); else exit 1; fi;)
  250.  
  251. web-answers:
  252. @$(foreach d,$(SECTION_DIRS),if $(MAKE) -C $d web-answers NOINIT=x SECTION=$(notdir $(d)); then $(TRUE); else exit 1; fi;)
  253.  
  254.  
  255. ################################################################################
  256. #
  257. # Build print version only. NOINIT and SECTION should be exported to all
  258. # these sub-makes.
  259. #
  260. print: general-graphics print-questions print-answers
  261.  
  262. print-questions: section-questions handbook.pdf handbook-2up.pdf question-pdfs
  263.  
  264. section-questions:
  265. @$(foreach d,$(SECTION_DIRS),if $(MAKE) -C $d print-questions NOINIT=x SECTION=$(notdir $(d)); then $(TRUE); else exit 1; fi;)
  266.  
  267. handbook.tex: handbook_template.tex $(QUESTION_TEX_INPUTS) $(LOCAL_HANDBOOK_INCLUDE)/questions.patterns $(LATEX_INCLUDES)
  268. @$(ANNOUNCE) "Generating $@"
  269. @$(ECHO) "% THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT!" > $@
  270. @$(ECHO) >> $@
  271. @$(PERL) -p -e "s|\<\@SHOWANSWERS\@\>|hideanswers|;" \
  272. -e "s|\<\@PAPEROPTIONS\@\>|$(PAPER_OPTIONS)|;" \
  273. $(foreach sect,$(SECTION_DIRS),-e "s|\<\@SECTION\[$(notdir $(sect))\]\@\>|\\\\input{$(basename $(filter $(sect)/%,$(QUESTION_TEX_INPUTS)))}|;") $< >> $@
  274.  
  275. question-pdfs:
  276. @$(foreach d,$(SECTION_DIRS),if $(MAKE) -C $d question-pdfs NOINIT=x SECTION=$(notdir $(d)); then $(TRUE); else exit 1; fi;)
  277.  
  278. #
  279. # Answers
  280. #
  281. print-answers: section-answers handbook-answers.pdf handbook-answers-2up.pdf answer-pdfs
  282.  
  283. section-answers:
  284. @$(foreach d,$(SECTION_DIRS),if $(MAKE) -C $d print-answers NOINIT=x SECTION=$(notdir $(d)); then $(TRUE); else exit 1; fi;)
  285.  
  286. handbook-answers.tex: handbook_template.tex $(ANSWER_TEX_INPUTS) $(LOCAL_HANDBOOK_INCLUDE)/answers.patterns $(LATEX_INCLUDES)
  287. @$(ANNOUNCE) "Generating $@"
  288. @$(ECHO) "% THIS FILE IS AUTOMATICALLY GENERATED. DO NOT EDIT!" > $@
  289. @$(ECHO) >> $@
  290. @$(PERL) -p -e "s|\<\@SHOWANSWERS\@\>|showanswers|;" \
  291. -e "s|\<\@PAPEROPTIONS\@\>|$(PAPER_OPTIONS)|;" \
  292. $(foreach sect,$(SECTION_DIRS),-e "s|\<\@SECTION\[$(notdir $(sect))\]\@\>|\\\\input{$(basename $(filter $(sect)/%,$(ANSWER_TEX_INPUTS)))}|;") $< >> $@
  293.  
  294. answer-pdfs:
  295. @$(foreach d,$(SECTION_DIRS),if $(MAKE) -C $d answer-pdfs NOINIT=x SECTION=$(notdir $(d)); then $(TRUE); else exit 1; fi;)
  296.  
  297. #
  298. # Generic rules for print version.
  299. #
  300. %.pdf: %.tex
  301. @$(ANNOUNCE) "pdflatex $< (pass 1)"
  302. $(PDFLATEX) --jobname=$(basename $<) '\def\LaTeXOptions{12pt,a4paper}\input{$<}'
  303. @$(ANNOUNCE) "pdflatex $< (pass 2)"
  304. $(PDFLATEX) --jobname=$(basename $<) '\def\LaTeXOptions{12pt,a4paper}\input{$<}'
  305.  
  306. %-2up.pdf: %.pdf
  307. @$(ANNOUNCE) "Generating $@"
  308. $(PDFNUP) --nup 2x1 --outfile $@ $<
  309.  
  310.  
  311. ################################################################################
  312. #
  313. # Build any general graphics that are used throughout the handbook. This uses
  314. # the standard makefile for a content directory, but the only files in this
  315. # directory are graphics files.
  316. #
  317. general-graphics:
  318. @if $(MAKE) -C graphics general-graphics BUILD_DIR=$(CURDIR); then $(TRUE); else exit 1; fi
  319.  
  320.  
  321. ################################################################################
  322. #
  323. # Deploy the appropriate files into a shared folder, which is then synchronised
  324. # with Blackboard. This relies on the environment variable HANDBOOK_INSTALL_ROOT
  325. # being defined, and (assuming that this variable points to a directory on the
  326. # network) the appropriate share has been mounted.
  327. #
  328. # See build_document_rules.make for an explanation of why the install
  329. # uses a foreach.
  330. #
  331. install: questions answers
  332. @$(SITECOPY) --catchup Blackboard$(PAPER_NUMBER)
  333. @$(ANNOUNCE) "Deploying handbook files to Blackboard --- make sure that you have the share mounted!"
  334. @$(TEST) -d $(HANDBOOK_INSTALL_ROOT)
  335. @$(MKDIR_P) $(INSTALL_DIRECTORY)
  336. @$(foreach d,$(SECTION_DIRS),if $(MAKE) -C $d $@ NOINIT=x SECTION=$(notdir $(d)); then $(TRUE); else exit 1; fi;)
  337. @$(ANNOUNCE) "Deploying files into $(INSTALL_DIRECTORY)"
  338. @$(foreach f,$(QUESTION_INSTALL_FILES),if $(TEST) ! -f $(INSTALL_DIRECTORY)/$(f) -o $(f) -nt $(INSTALL_DIRECTORY)/$(f); then $(ECHO) "Deploying $(f)"; $(CP) $(f) $(INSTALL_DIRECTORY); fi;)
  339. @$(foreach f,$(ANSWER_INSTALL_FILES),if $(TEST) ! -f $(INSTALL_DIRECTORY)/$(f) -o $(f) -nt $(INSTALL_DIRECTORY)/$(f); then $(ECHO) "Deploying $(f)"; $(CP) $(f) $(INSTALL_DIRECTORY); fi;)
  340. @$(ANNOUNCE) "Synchronising with Blackboard"
  341. @$(SITECOPY) --update Blackboard$(PAPER_NUMBER)
  342.  
  343.  
  344. ################################################################################
  345. #
  346. # Clean up all generated files.
  347. # "web-clean" and "print-clean" only clean up files for the web and print
  348. # versions, respectively. Note that "clean" isn't dependent on either
  349. # "web-clean" or "print-clean", to ensure that the correct target is
  350. # used when calling the sub-makefile.
  351. #
  352. clean:
  353. @$(foreach d,$(SECTION_DIRS),$(MAKE) -C $d $@;)
  354. ifneq ($(strip $(ALL_CLEAN_FILES)),)
  355. -$(RM) -f $(ALL_CLEAN_FILES)
  356. @$(MAKE) -C graphics clean BUILD_DIR=$(CURDIR)
  357. endif
  358.  
  359. web-clean:
  360. @$(foreach d,$(SECTION_DIRS),$(MAKE) -C $d $@;)
  361. ifneq ($(strip $(WEB_CLEAN_FILES)),)
  362. -$(RM) -f $(WEB_CLEAN_FILES)
  363. endif
  364.  
  365. print-clean:
  366. @$(foreach d,$(SECTION_DIRS),$(MAKE) -C $d $@;)
  367. ifneq ($(strip $(PRINT_CLEAN_FILES)),)
  368. -$(RM) -f $(PRINT_CLEAN_FILES)
  369. endif
  370.  
  371.  
  372. ################################################################################
  373. #
  374. # Debugging information, mostly lists of the generated variables.
  375. #
  376. debug:
  377. @$(ANNOUNCE) Externally defined variables
  378. @$(ECHO) "TEACHING_SHARED = [$(TEACHING_SHARED)]"
  379. @$(ECHO) "HANDBOOK_INSTALL_ROOT = [$(HANDBOOK_INSTALL_ROOT)]"
  380. @$(ANNOUNCE) Internally defined variables
  381. @$(ECHO) "GLOBAL_HANDBOOK_INCLUDE = [$(GLOBAL_HANDBOOK_INCLUDE)]"
  382. @$(ECHO) "LOCAL_HANDBOOK_INCLUDE = [$(LOCAL_HANDBOOK_INCLUDE)]"
  383. @$(ECHO) "SECTION_DIRS = [$(SECTION_DIRS)]"
  384. @$(ECHO) "QUESTION_TEX_INPUTS = [$(QUESTION_TEX_INPUTS)]"
  385. @$(ECHO) "ANSWER_TEX_INPUTS = [$(ANSWER_TEX_INPUTS)]"
  386. @$(ECHO) "LATEX_INCLUDES = [$(LATEX_INCLUDES)]"
  387. @$(ECHO) "INSTALL_DIRECTORY = [$(INSTALL_DIRECTORY)]"
  388. @$(ECHO) "INSTALL_FILES = [$(INSTALL_FILES)]"
  389. @$(ECHO) "QUESTION_INSTALL_FILES = [$(QUESTION_INSTALL_FILES)]"
  390. @$(ECHO) "ANSWER_INSTALL_FILES = [$(ANSWER_INSTALL_FILES)]"
  391. @$(ECHO) "QUESTION_INSTALL_PATTERNS = [$(QUESTION_INSTALL_PATTERNS)]"
  392. @$(ECHO) "ANSWER_INSTALL_PATTERNS = [$(ANSWER_INSTALL_PATTERNS)]"
  393. @$(ECHO) "WEB_CLEAN_FILES = [$(WEB_CLEAN_FILES)]"
  394. @$(ECHO) "PRINT_CLEAN_FILES = [$(PRINT_CLEAN_FILES)]"
  395. @$(ECHO) "ALL_CLEAN_FILES = [$(ALL_CLEAN_FILES)]"
  396. @$(ECHO) "SUBJECT_CODE = [$(SUBJECT_CODE)]"
  397. @$(ECHO) "PAPER_NUMBER = [$(PAPER_NUMBER)]"
  398. @$(ECHO) "PAPER_TITLE = [$(PAPER_TITLE)]"
  399. @$(ECHO) "PAPER_YEAR = [$(PAPER_YEAR)]"
  400. @$(ECHO) "PAPER_PERIOD = [$(PAPER_PERIOD)]"
  401. @$(ECHO) "HANDBOOK_AUTHORS = [$(HANDBOOK_AUTHORS)]"
  402. @$(ECHO) "PAPER_OPTIONS = [$(PAPER_OPTIONS)]"
  403.  
  404.  
  405. ################################################################################
  406. #
  407. # Print out the list of targets. Handy for when you forget!
  408. #
  409. targets:
  410. @$(ECHO) $(TARGETS)