summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-11-04 16:22:42 +1100
committerChris Johns <chrisj@rtems.org>2016-11-04 16:22:42 +1100
commit74194f7538a4aa177a16ba75428f0a0af82502c7 (patch)
treeee506361e094daaf405ab23af378d4af89056456
parent9024cfbc7f5ed421020d34d091ce31c99c53fe63 (diff)
downloadrtems-docs-74194f7538a4aa177a16ba75428f0a0af82502c7.tar.bz2
waf: Check for texlive packages and report an error is not found.
-rw-r--r--README.txt95
-rw-r--r--common/waf.py112
2 files changed, 198 insertions, 9 deletions
diff --git a/README.txt b/README.txt
index 68f4554..bf29299 100644
--- a/README.txt
+++ b/README.txt
@@ -30,25 +30,114 @@ FreeBSD
~~~~~~~
Sphinx:
+
# pkg install py27-sphinx
PDF:
+
# pkg install texlive-full
Single HTML:
+
# pkg install npm
# npm install -g inliner
+CentOS 7
+~~~~~~~~
+
+PDF:
+
+ # yum install -y texlive-*
+
+This does not provide all the require packages. Missing are:
+
+ capt-of
+ eqparbox
+ ifplatform
+ inconsolata
+ lato
+ upquote
+
+Latex Setup
+~~~~~~~~~~~
+
+Latex is used to create the PDF document. The setup of Latex varies from host
+to host operating system due to the way each host packages the texlive
+packages. There is no common naming and no real way to figure what texlive
+package is present in a host's packaging. It seems not all of texlive is
+available.
+
+The RTEMS Documentation waf configure phase check for each texlive package used
+in the generated output and the styles. If you complete configure with the
+--pdf option you should be able to build PDF documentation.
+
+The texlive package requirments come from the Latex styles we are using and
+Sphinx.
+
+An example of a failure is a default CentOS 7:
+
+ Checking for Tex package 'Bjarne' : ok
+ Checking for Tex package 'alltt' : ok
+ Checking for Tex package 'amsmath' : ok
+ Checking for Tex package 'amssymb' : ok
+ Checking for Tex package 'amstext' : ok
+ Checking for Tex package 'array' : ok
+ Checking for Tex package 'atbegshi' : ok
+ Checking for Tex package 'babel' : ok
+ Checking for Tex package 'calc' : ok
+ Checking for Tex package 'capt-of' : not found (please install)
+ Checking for Tex package 'charter' : ok
+ Checking for Tex package 'cmap' : ok
+ Checking for Tex package 'color' : ok
+ Checking for Tex package 'eqparbox' : not found (please install)
+ Checking for Tex package 'etoolbox' : ok
+ Checking for Tex package 'fancybox' : ok
+ Checking for Tex package 'fancyhdr' : ok
+ Checking for Tex package 'fancyvrb' : ok
+ Checking for Tex package 'float' : ok
+ Checking for Tex package 'fncychap' : ok
+ Checking for Tex package 'fontenc' : ok
+ Checking for Tex package 'footnote' : ok
+ Checking for Tex package 'framed' : ok
+ Checking for Tex package 'graphicx' : ok
+ Checking for Tex package 'hypcap' : ok
+ Checking for Tex package 'hyperref' : ok
+ Checking for Tex package 'ifplatform' : not found (please install)
+ Checking for Tex package 'ifthen' : ok
+ Checking for Tex package 'inconsolata' : not found (please install)
+ Checking for Tex package 'inputenc' : ok
+ Checking for Tex package 'keyval' : ok
+ Checking for Tex package 'kvoptions' : ok
+ Checking for Tex package 'lato' : not found (please install)
+ Checking for Tex package 'lineno' : ok
+ Checking for Tex package 'longtable' : ok
+ Checking for Tex package 'makeidx' : ok
+ Checking for Tex package 'multirow' : ok
+ Checking for Tex package 'parskip' : ok
+ Checking for Tex package 'pdftexcmds' : ok
+ Checking for Tex package 'textcomp' : ok
+ Checking for Tex package 'threeparttable' : ok
+ Checking for Tex package 'times' : ok
+ Checking for Tex package 'titlesec' : ok
+ Checking for Tex package 'upquote' : not found (please install)
+ Checking for Tex package 'utf8' : ok
+ Checking for Tex package 'wrapfig' : ok
+ Checking for Tex package 'xcolor' : ok
+ Checking for Tex package 'xstring' : ok
+ There are 6 Tex package failures. Please fix.
+
+If you find there is an issue please post the developers list.
+
Building
--------
To build enter in the top directory:
- $ ./waf configure [--pdf] [--singlehtml] [--prefix]
+ $ ./waf configure [--pdf] [--singlehtml] [--prefix] [--sphinx-verbose]
$ ./waf
-The '--pdf' and '--singlehtml' options can be added to build those output
-formats.
+The '--pdf' and '--singlehtml' options can be added to configure to build those
+output formats.
To build and install to a specific location:
diff --git a/common/waf.py b/common/waf.py
index 80e8b28..25f3d74 100644
--- a/common/waf.py
+++ b/common/waf.py
@@ -108,6 +108,101 @@ def html_resources(ctx, buildtype):
# target = [x.srcpath().replace("../", "") for x in files]
# )
+def latex_configure_tests(conf):
+
+ #
+ # Using a hint from ita (thank you) :
+ # https://github.com/waf-project/waf/blob/master/demos/tex/wscript
+ #
+ latex_test_preamble = ['\\newif\\ifsphinxKeepOldNames \\sphinxKeepOldNamestrue',
+ '\documentclass[a4paper,11pt,english]{report}']
+ latex_test_postamble = ['\\begin{document} test \\end{document}']
+ latex_tests = {
+ 'Bjarne' : ['\\usepackage[Bjarne]{fncychap}'],
+ 'alltt' : ['\\usepackage{alltt}'],
+ 'amsmath' : ['\\usepackage{amsmath}'],
+ 'amssymb' : ['\\usepackage{amssymb}'],
+ 'amstext' : ['\\usepackage{amstext}'],
+ 'array' : ['\\usepackage{array}'],
+ 'atbegshi' : ['\\usepackage{atbegshi}'],
+ 'babel' : ['\\usepackage{babel}'],
+ 'babel' : ['\\usepackage{babel}'],
+ 'calc' : ['\\usepackage{calc}'],
+ 'capt-of' : ['\\usepackage{capt-of}'],
+ 'charter' : ['\\usepackage{charter}'],
+ 'cmap' : ['\\usepackage{cmap}'],
+ 'color' : ['\\usepackage{color}'],
+ 'eqparbox' : ['\\usepackage{eqparbox}'],
+ 'etoolbox' : ['\\usepackage{etoolbox}'],
+ 'fancybox' : ['\\usepackage{fancybox}'],
+ 'fancyhdr' : ['\\usepackage{fancyhdr}'],
+ 'fancyvrb' : ['\\usepackage{fancyvrb}'],
+ 'float' : ['\\usepackage{float}'],
+ 'fncychap' : ['\\usepackage{fncychap}'],
+ 'fontenc' : ['\\usepackage[T1]{fontenc}'],
+ 'footnote' : ['\\usepackage{footnote}'],
+ 'framed' : ['\\usepackage{framed}'],
+ 'graphicx' : ['\\usepackage{graphicx}'],
+ 'hypcap' : ['\\usepackage{hyperref}',
+ '\\usepackage{hypcap}'],
+ 'hyperref' : ['\\usepackage{hyperref}'],
+ 'ifplatform' : ['\\usepackage{ifplatform}'],
+ 'ifthen' : ['\\usepackage{ifthen}'],
+ 'inconsolata' : ['\\usepackage{inconsolata}'],
+ 'inputenc' : ['\\usepackage{inputenc}'],
+ 'keyval' : ['\\usepackage{keyval}'],
+ 'kvoptions' : ['\\usepackage{kvoptions}'],
+ 'lato' : ['\\usepackage{lato}'],
+ 'lineno' : ['\\usepackage{lineno}'],
+ 'longtable' : ['\\usepackage{longtable}'],
+ 'makeidx' : ['\\usepackage{makeidx}'],
+ 'multirow' : ['\\usepackage{multirow}'],
+ 'parskip' : ['\\usepackage{parskip}'],
+ 'pdftexcmds' : ['\\usepackage{pdftexcmds}'],
+ 'textcomp' : ['\\usepackage{textcomp}'],
+ 'threeparttable' : ['\\usepackage{threeparttable}'],
+ 'times' : ['\\usepackage{times}'],
+ 'titlesec' : ['\\usepackage{titlesec}'],
+ 'upquote' : ['\\usepackage{upquote}'],
+ 'utf8' : ['\\usepackage[utf8]{inputenc}'],
+ 'wrapfig' : ['\\usepackage{wrapfig}'],
+ 'xcolor' : ['\\usepackage{xcolor}'],
+ 'xstring' : ['\\usepackage{xstring}'],
+ }
+
+ def build_latex_test(bld):
+ def create_tex(test_data):
+ return os.linesep.join(latex_test_preamble +
+ test_data +
+ latex_test_postamble)
+ def write_tex_test(tsk):
+ tex = create_tex(tsk.env.TEST_DATA)
+ tsk.outputs[0].write(tex)
+
+ test = bld.kw['tex_test']
+ bld.env.TEST = test
+ bld.env.TEST_DATA = latex_tests[test]
+
+ bld.to_log('%s.tex %s' % (test, '=' * (40 - len(test) + 5)))
+ bld.to_log(create_tex(latex_tests[test]))
+ bld.to_log('=' * 40)
+
+ bld(rule = write_tex_test, target = 'main.tex')
+ bld(features = 'tex', type = 'pdflatex', source = 'main.tex', prompt = 0)
+
+ fails = 0
+ for t in sorted(latex_tests.keys()):
+ r = conf.test(build_fun = build_latex_test,
+ msg = "Checking for Tex package '%s'" % (t),
+ tex_test = t,
+ okmsg = 'ok',
+ errmsg = 'not found (please install)',
+ mandatory = False)
+ if r is None:
+ fails += 1
+ if fails > 0:
+ conf.fatal('There are %d Tex package failures. Please fix.' % (fails))
+
def cmd_configure(ctx):
ctx.find_program("sphinx-build", var="BIN_SPHINX_BUILD", mandatory = True)
ctx.find_program("aspell", var = "BIN_ASPELL", mandatory = False)
@@ -129,13 +224,18 @@ def cmd_configure(ctx):
#
ctx.env.BUILD_PDF = 'no'
if ctx.options.pdf:
+ check_tex = not ctx.env.PDFLATEX
+ if check_tex:
+ ctx.load('tex')
+ if not ctx.env.PDFLATEX or not ctx.env.MAKEINDEX:
+ ctx.fatal('The programs pdflatex and makeindex are required for PDF output')
+ if 'PDFLATEXFLAGS' not in ctx.env or \
+ '-shell-escape' not in ctx.env['PDFLATEXFLAGS']:
+ ctx.env.append_value('PDFLATEXFLAGS', '-shell-escape')
+ latex_configure_tests(ctx)
+ else:
+ ctx.msg('Check for Tex packages', 'skipping, already checked')
ctx.env.BUILD_PDF = 'yes'
- ctx.load('tex')
- if not ctx.env.PDFLATEX or not ctx.env.MAKEINDEX:
- ctx.fatal('The programs pdflatex and makeindex are required for PDF output')
- if 'PDFLATEXFLAGS' not in ctx.env or \
- '-shell-escape' not in ctx.env['PDFLATEXFLAGS']:
- ctx.env.append_value('PDFLATEXFLAGS', '-shell-escape')
ctx.envBUILD_SINGLEHTML = 'no'
if ctx.options.singlehtml: