From a9edc15a5ac66ba8794e66e8e9c0a1f926009220 Mon Sep 17 00:00:00 2001 From: Dirk Baechle Date: Sat, 21 Dec 2013 01:24:25 +0100 Subject: - added EPUB Builder to the DocBook Tool, based on the work of Andrew Featherstone --- doc/generated/builders.gen | 26 ++ doc/generated/builders.mod | 4 + doc/generated/functions.gen | 22 ++ doc/generated/functions.mod | 4 + doc/generated/tools.gen | 5 +- doc/generated/variables.gen | 9 + doc/generated/variables.mod | 2 + doc/man/SConstruct | 11 +- doc/user/SConstruct | 11 +- src/CHANGES.txt | 3 + src/engine/SCons/Tool/docbook/__init__.py | 135 +++++++++- src/engine/SCons/Tool/docbook/__init__.xml | 34 ++- test/Docbook/basic/epub/epub.py | 62 +++++ test/Docbook/basic/epub/image/SConstruct | 2 + test/Docbook/basic/epub/image/manual.xml | 388 +++++++++++++++++++++++++++++ 15 files changed, 688 insertions(+), 30 deletions(-) create mode 100644 test/Docbook/basic/epub/epub.py create mode 100644 test/Docbook/basic/epub/image/SConstruct create mode 100644 test/Docbook/basic/epub/image/manual.xml diff --git a/doc/generated/builders.gen b/doc/generated/builders.gen index 5cd92f2..41239d4 100644 --- a/doc/generated/builders.gen +++ b/doc/generated/builders.gen @@ -84,6 +84,32 @@ env.CXXFile(target = 'bar', source = 'bar.yy') + + + DocbookEpub() + + + env.DocbookEpub() + + + +A pseudo-Builder, providing a Docbook toolchain for EPUB output. + + +env = Environment(tools=['docbook']) +env.DocbookEpub('manual.epub', 'manual.xml') + + + +or simply + + +env = Environment(tools=['docbook']) +env.DocbookEpub('manual') + + + + DocbookHtml() diff --git a/doc/generated/builders.mod b/doc/generated/builders.mod index b8c7d80..50591b4 100644 --- a/doc/generated/builders.mod +++ b/doc/generated/builders.mod @@ -11,6 +11,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. CFile"> Command"> CXXFile"> +DocbookEpub"> DocbookHtml"> DocbookHtmlChunked"> DocbookHtmlhelp"> @@ -65,6 +66,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. env.CFile"> env.Command"> env.CXXFile"> +env.DocbookEpub"> env.DocbookHtml"> env.DocbookHtmlChunked"> env.DocbookHtmlhelp"> @@ -129,6 +131,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. CFile"> Command"> CXXFile"> +DocbookEpub"> DocbookHtml"> DocbookHtmlChunked"> DocbookHtmlhelp"> @@ -183,6 +186,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. env.CFile"> env.Command"> env.CXXFile"> +env.DocbookEpub"> env.DocbookHtml"> env.DocbookHtmlChunked"> env.DocbookHtmlhelp"> diff --git a/doc/generated/functions.gen b/doc/generated/functions.gen index 4849ac6..072b91c 100644 --- a/doc/generated/functions.gen +++ b/doc/generated/functions.gen @@ -3419,6 +3419,28 @@ Progress(['-\r', '\\\r', '|\r', '/\r'], interval=5) + + + Pseudo(target, ...) + + + env.Pseudo(target, ...) + + + +This indicates that each given +target +should not be created by the build rule, and if the target is created, +an error will be generated. This is similar to the gnu make .PHONY +target. However, in the vast majority of cases, an +Alias +is more appropriate. + +Multiple targets can be passed in to a single call to +Pseudo. + + + env.RCS() diff --git a/doc/generated/functions.mod b/doc/generated/functions.mod index 0f5dd21..99aaa48 100644 --- a/doc/generated/functions.mod +++ b/doc/generated/functions.mod @@ -71,6 +71,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. PrependENVPath"> PrependUnique"> Progress"> +Pseudo"> RCS"> Replace"> Repository"> @@ -158,6 +159,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. env.PrependENVPath"> env.PrependUnique"> env.Progress"> +env.Pseudo"> env.RCS"> env.Replace"> env.Repository"> @@ -255,6 +257,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. PrependENVPath"> PrependUnique"> Progress"> +Pseudo"> RCS"> Replace"> Repository"> @@ -342,6 +345,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. env.PrependENVPath"> env.PrependUnique"> env.Progress"> +env.Pseudo"> env.RCS"> env.Replace"> env.Repository"> diff --git a/doc/generated/tools.gen b/doc/generated/tools.gen index 7d75638..a0a709e 100644 --- a/doc/generated/tools.gen +++ b/doc/generated/tools.gen @@ -222,7 +222,7 @@ accordingly. The rules given above are valid for the Builders DocbookHtml, -DocbookPdf, DocbookSlidesPdf and DocbookXInclude. For the +DocbookPdf, DocbookEpub, DocbookSlidesPdf and DocbookXInclude. For the DocbookMan transformation you can specify a target name, but the actual output names are automatically set from the refname entries in your XML source. @@ -261,6 +261,7 @@ variables for setting the default XSL name is provided. These are: DOCBOOK_DEFAULT_XSL_HTMLCHUNKED DOCBOOK_DEFAULT_XSL_HTMLHELP DOCBOOK_DEFAULT_XSL_PDF +DOCBOOK_DEFAULT_XSL_EPUB DOCBOOK_DEFAULT_XSL_MAN DOCBOOK_DEFAULT_XSL_SLIDESPDF DOCBOOK_DEFAULT_XSL_SLIDESHTML @@ -272,7 +273,7 @@ DOCBOOK_DEFAULT_XSL_SLIDESHTML DOCBOOK_DEFAULT_XSL_PDF='pdf.xsl') env.DocbookHtml('manual') # now uses html.xsl -Sets: &cv-link-DOCBOOK_DEFAULT_XSL_HTML;, &cv-link-DOCBOOK_DEFAULT_XSL_HTMLCHUNKED;, &cv-link-DOCBOOK_DEFAULT_XSL_HTMLHELP;, &cv-link-DOCBOOK_DEFAULT_XSL_MAN;, &cv-link-DOCBOOK_DEFAULT_XSL_PDF;, &cv-link-DOCBOOK_DEFAULT_XSL_SLIDESHTML;, &cv-link-DOCBOOK_DEFAULT_XSL_SLIDESPDF;, &cv-link-DOCBOOK_FOP;, &cv-link-DOCBOOK_FOPCOM;, &cv-link-DOCBOOK_FOPFLAGS;, &cv-link-DOCBOOK_XMLLINT;, &cv-link-DOCBOOK_XMLLINTCOM;, &cv-link-DOCBOOK_XMLLINTFLAGS;, &cv-link-DOCBOOK_XSLTPROC;, &cv-link-DOCBOOK_XSLTPROCCOM;, &cv-link-DOCBOOK_XSLTPROCFLAGS;, &cv-link-DOCBOOK_XSLTPROCPARAMS;.Uses: &cv-link-DOCBOOK_FOPCOMSTR;, &cv-link-DOCBOOK_XMLLINTCOMSTR;, &cv-link-DOCBOOK_XSLTPROCCOMSTR;. +Sets: &cv-link-DOCBOOK_DEFAULT_XSL_EPUB;, &cv-link-DOCBOOK_DEFAULT_XSL_HTML;, &cv-link-DOCBOOK_DEFAULT_XSL_HTMLCHUNKED;, &cv-link-DOCBOOK_DEFAULT_XSL_HTMLHELP;, &cv-link-DOCBOOK_DEFAULT_XSL_MAN;, &cv-link-DOCBOOK_DEFAULT_XSL_PDF;, &cv-link-DOCBOOK_DEFAULT_XSL_SLIDESHTML;, &cv-link-DOCBOOK_DEFAULT_XSL_SLIDESPDF;, &cv-link-DOCBOOK_FOP;, &cv-link-DOCBOOK_FOPCOM;, &cv-link-DOCBOOK_FOPFLAGS;, &cv-link-DOCBOOK_XMLLINT;, &cv-link-DOCBOOK_XMLLINTCOM;, &cv-link-DOCBOOK_XMLLINTFLAGS;, &cv-link-DOCBOOK_XSLTPROC;, &cv-link-DOCBOOK_XSLTPROCCOM;, &cv-link-DOCBOOK_XSLTPROCFLAGS;, &cv-link-DOCBOOK_XSLTPROCPARAMS;.Uses: &cv-link-DOCBOOK_FOPCOMSTR;, &cv-link-DOCBOOK_XMLLINTCOMSTR;, &cv-link-DOCBOOK_XSLTPROCCOMSTR;. dvi diff --git a/doc/generated/variables.gen b/doc/generated/variables.gen index ee5a0dd..efdac8e 100644 --- a/doc/generated/variables.gen +++ b/doc/generated/variables.gen @@ -909,6 +909,15 @@ into a list of Dir instances relative to the target being built. + + DOCBOOK_DEFAULT_XSL_EPUB + + +The default XSLT file for the DocbookEpub builder within the +current environment, if no other XSLT gets specified via keyword. + + + DOCBOOK_DEFAULT_XSL_HTML diff --git a/doc/generated/variables.mod b/doc/generated/variables.mod index 8a898ec..b55b218 100644 --- a/doc/generated/variables.mod +++ b/doc/generated/variables.mod @@ -70,6 +70,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $DESCRIPTION_lang"> $Dir"> $Dirs"> +$DOCBOOK_DEFAULT_XSL_EPUB"> $DOCBOOK_DEFAULT_XSL_HTML"> $DOCBOOK_DEFAULT_XSL_HTMLCHUNKED"> $DOCBOOK_DEFAULT_XSL_HTMLHELP"> @@ -651,6 +652,7 @@ THIS IS AN AUTOMATICALLY-GENERATED FILE. DO NOT EDIT. $DESCRIPTION_lang"> $Dir"> $Dirs"> +$DOCBOOK_DEFAULT_XSL_EPUB"> $DOCBOOK_DEFAULT_XSL_HTML"> $DOCBOOK_DEFAULT_XSL_HTMLCHUNKED"> $DOCBOOK_DEFAULT_XSL_HTMLHELP"> diff --git a/doc/man/SConstruct b/doc/man/SConstruct index cfdbb2d..927bfa2 100644 --- a/doc/man/SConstruct +++ b/doc/man/SConstruct @@ -62,14 +62,7 @@ if env.WhereIs('gs'): # Create the EPUB format # if has_gs and has_pdf: - metainf = env.Command('META-INF','',[Mkdir('META-INF'), Mkdir('OEBPS')]) - css = env.Command('OEBPS/epub.css','epub.css',[Copy('OEBPS/epub.css','epub.css')]) - env.Depends(css, metainf) jpg = env.Gs('OEBPS/cover.jpg','scons-scons.pdf', GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -dJPEGQ=100 -r72x72 -q') - env.Depends(jpg, metainf) - oebps = env.DocbookXslt('OEBPS/toc.ncx', 'scons_db.xml', xsl='epub.xsl') - env.Depends(oebps, jpg) - env.Zip('scons-man.epub', 'OEBPS', ZIPFLAGS='-Xr9D') - env.Clean(oebps, Glob('OEBPS/*.*')) - env.Clean(oebps, Glob('META-INF/*.*')) + epub = env.DocbookEpub('scons-man.epub', 'scons_db.xml', xsl='epub.xsl') + env.Depends(epub, jpg) diff --git a/doc/user/SConstruct b/doc/user/SConstruct index 5d36a5e..701fb7b 100644 --- a/doc/user/SConstruct +++ b/doc/user/SConstruct @@ -60,14 +60,7 @@ if env.WhereIs('gs'): # Create the EPUB format # if has_gs and has_pdf: - metainf = env.Command('META-INF','',[Mkdir('META-INF'), Mkdir('OEBPS')]) - css = env.Command('OEBPS/epub.css','epub.css',[Copy('OEBPS/epub.css','epub.css')]) - env.Depends(css, metainf) jpg = env.Gs('OEBPS/cover.jpg','scons-user.pdf', GSFLAGS='-dNOPAUSE -dBATCH -sDEVICE=jpeg -dFirstPage=1 -dLastPage=1 -dJPEGQ=100 -r72x72 -q') - env.Depends(jpg, metainf) - oebps = env.DocbookXslt('OEBPS/toc.ncx', 'scons_db.xml', xsl='epub.xsl') - env.Depends(oebps, jpg) - env.Zip('scons-user.epub', 'OEBPS', ZIPFLAGS='-Xr9D') - env.Clean(oebps, Glob('OEBPS/*.*')) - env.Clean(oebps, Glob('META-INF/*.*')) + epub = env.DocbookEpub('scons-user.epub', 'scons_db.xml', xsl='epub.xsl') + env.Depends(epub, jpg) diff --git a/src/CHANGES.txt b/src/CHANGES.txt index 8b24696..10f940a 100644 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -6,6 +6,9 @@ RELEASE 2.3.1.alpha.yyyymmdd - NEW DATE WILL BE INSERTED HERE + From Andrew Featherstone: + - Added support for EPUB output format to the DocBook tool. + From Tom Tanner: - Stop leaking file handles to subprocesses by switching to using subprocess always. diff --git a/src/engine/SCons/Tool/docbook/__init__.py b/src/engine/SCons/Tool/docbook/__init__.py index 1e88cfe..a336992 100644 --- a/src/engine/SCons/Tool/docbook/__init__.py +++ b/src/engine/SCons/Tool/docbook/__init__.py @@ -318,9 +318,14 @@ def __build_lxml(target, source, env): """ from lxml import etree + xslt_ac = etree.XSLTAccessControl(read_file=True, + write_file=True, + create_dir=True, + read_network=False, + write_network=False) xsl_style = env.subst('$DOCBOOK_XSL') xsl_tree = etree.parse(xsl_style) - transform = etree.XSLT(xsl_tree) + transform = etree.XSLT(xsl_tree, access_control=xslt_ac) doc = etree.parse(str(source[0])) # Support for additional parameters parampass = {} @@ -404,6 +409,116 @@ __fop_builder = SCons.Builder.Builder( src_suffix = '.fo', ensure_suffix=1) +def DocbookEpub(env, target, source=None, *args, **kw): + """ + A pseudo-Builder, providing a Docbook toolchain for ePub output. + """ + import zipfile + import shutil + from lxml import etree + + def build_open_container(target, source, env): + """Generate the *.epub file from intermediate outputs + + Constructs the epub file according to the Open Container Format. This + function could be replaced by a call to the SCons Zip builder if support + was added for different compression formats for separate source nodes. + """ + zf = zipfile.ZipFile(str(target[0]), 'w') + mime_file = open('mimetype', 'w') + mime_file.write('application/epub+zip') + mime_file.close() + zf.write(mime_file.name, compress_type = zipfile.ZIP_STORED) + for s in source: + for dirpath, dirnames, filenames in os.walk(str(s)): + for fname in filenames: + path = os.path.join(dirpath, fname) + if os.path.isfile(path): + zf.write(path, os.path.relpath(path, str(env.get('ZIPROOT', ''))), + zipfile.ZIP_DEFLATED) + zf.close() + + def add_resources(target, source, env): + """Add missing resources to the OEBPS directory + + Ensure all the resources in the manifest are present in the OEBPS directory. + """ + hrefs = [] + content_file = os.path.join(source[0].abspath, 'content.opf') + if not os.path.isfile(content_file): + return + + hrefs = [] + if has_libxml2: + nsmap = {'opf' : 'http://www.idpf.org/2007/opf'} + # Read file and resolve entities + doc = libxml2.readFile(content_file, None, 0) + opf = doc.getRootElement() + # Create xpath context + xpath_context = doc.xpathNewContext() + # Register namespaces + for key, val in nsmap.iteritems(): + xpath_context.xpathRegisterNs(key, val) + + if hasattr(opf, 'xpathEval') and xpath_context: + # Use the xpath context + xpath_context.setContextNode(opf) + items = xpath_context.xpathEval(".//opf:item") + else: + items = opf.findall(".//{'http://www.idpf.org/2007/opf'}item") + + for item in items: + if hasattr(item, 'prop'): + hrefs.append(item.prop('href')) + else: + hrefs.append(item.attrib['href']) + + doc.freeDoc() + xpath_context.xpathFreeContext() + elif has_lxml: + from lxml import etree + + opf = etree.parse(content_file) + # All the opf:item elements are resources + for item in opf.xpath('//opf:item', + namespaces= { 'opf': 'http://www.idpf.org/2007/opf' }): + hrefs.append(item.attrib['href']) + + for href in hrefs: + # If the resource was not already created by DocBook XSL itself, + # copy it into the OEBPS folder + referenced_file = os.path.join(source[0].abspath, href) + if not os.path.exists(referenced_file): + shutil.copy(href, os.path.join(source[0].abspath, href)) + + # Init list of targets/sources + target, source = __extend_targets_sources(target, source) + + # Init XSL stylesheet + __init_xsl_stylesheet(kw, env, '$DOCBOOK_DEFAULT_XSL_EPUB', ['epub','docbook.xsl']) + + # Setup builder + __builder = __select_builder(__lxml_builder, __libxml2_builder, __xsltproc_builder) + + # Create targets + result = [] + tlist = ['OEBPS/toc.ncx', 'META-INF/container.xml'] + dirs = [SCons.Script.Dir('OEBPS'), SCons.Script.Dir('META-INF')] + r = __builder.__call__(env, tlist, source[0], **kw) + + env.Depends(r, kw['DOCBOOK_XSL']) + result.extend(r) + + container = env.Command(__ensure_suffix(str(target[0]), '.epub'), + tlist, [add_resources, build_open_container]) + + env.Depends(container, r) + result.extend(container) + # Add supporting files for cleanup + env.Clean(r, dirs + [SCons.Script.File('mimetype')]) + + return result + def DocbookHtml(env, target, source=None, *args, **kw): """ A pseudo-Builder, providing a Docbook toolchain for HTML output. @@ -686,19 +801,19 @@ def DocbookXslt(env, target, source=None, *args, **kw): return result - def generate(env): """Add Builders and construction variables for docbook to an Environment.""" env.SetDefault( # Default names for customized XSL stylesheets - DOCBOOK_DEFAULT_XSL_HTML = '', - DOCBOOK_DEFAULT_XSL_HTMLCHUNKED = '', - DOCBOOK_DEFAULT_XSL_HTMLHELP = '', - DOCBOOK_DEFAULT_XSL_PDF = '', - DOCBOOK_DEFAULT_XSL_MAN = '', - DOCBOOK_DEFAULT_XSL_SLIDESPDF = '', - DOCBOOK_DEFAULT_XSL_SLIDESHTML = '', + DOCBOOK_DEFAULT_XSL_EPUB = '', + DOCBOOK_DEFAULT_XSL_HTML = '', + DOCBOOK_DEFAULT_XSL_HTMLCHUNKED = '', + DOCBOOK_DEFAULT_XSL_HTMLHELP = '', + DOCBOOK_DEFAULT_XSL_PDF = '', + DOCBOOK_DEFAULT_XSL_MAN = '', + DOCBOOK_DEFAULT_XSL_SLIDESPDF = '', + DOCBOOK_DEFAULT_XSL_SLIDESHTML = '', # Paths to the detected executables DOCBOOK_XSLTPROC = '', @@ -725,6 +840,7 @@ def generate(env): _detect(env) try: + env.AddMethod(DocbookEpub, "DocbookEpub") env.AddMethod(DocbookHtml, "DocbookHtml") env.AddMethod(DocbookHtmlChunked, "DocbookHtmlChunked") env.AddMethod(DocbookHtmlhelp, "DocbookHtmlhelp") @@ -737,6 +853,7 @@ def generate(env): except AttributeError: # Looks like we use a pre-0.98 version of SCons... from SCons.Script.SConscript import SConsEnvironment + SConsEnvironment.DocbookEpub = DocbookEpub SConsEnvironment.DocbookHtml = DocbookHtml SConsEnvironment.DocbookHtmlChunked = DocbookHtmlChunked SConsEnvironment.DocbookHtmlhelp = DocbookHtmlhelp diff --git a/src/engine/SCons/Tool/docbook/__init__.xml b/src/engine/SCons/Tool/docbook/__init__.xml index be2f2ca..0748738 100644 --- a/src/engine/SCons/Tool/docbook/__init__.xml +++ b/src/engine/SCons/Tool/docbook/__init__.xml @@ -97,7 +97,7 @@ accordingly. The rules given above are valid for the Builders &b-link-DocbookHtml;, -&b-link-DocbookPdf;, &b-link-DocbookSlidesPdf; and &b-link-DocbookXInclude;. For the +&b-link-DocbookPdf;, &b-link-DocbookEpub;, &b-link-DocbookSlidesPdf; and &b-link-DocbookXInclude;. For the &b-link-DocbookMan; transformation you can specify a target name, but the actual output names are automatically set from the refname entries in your XML source. @@ -136,6 +136,7 @@ variables for setting the default XSL name is provided. These are: DOCBOOK_DEFAULT_XSL_HTMLCHUNKED DOCBOOK_DEFAULT_XSL_HTMLHELP DOCBOOK_DEFAULT_XSL_PDF +DOCBOOK_DEFAULT_XSL_EPUB DOCBOOK_DEFAULT_XSL_MAN DOCBOOK_DEFAULT_XSL_SLIDESPDF DOCBOOK_DEFAULT_XSL_SLIDESHTML @@ -153,6 +154,7 @@ env.DocbookHtml('manual') # now uses html.xsl DOCBOOK_DEFAULT_XSL_HTMLCHUNKED DOCBOOK_DEFAULT_XSL_HTMLHELP DOCBOOK_DEFAULT_XSL_PDF +DOCBOOK_DEFAULT_XSL_EPUB DOCBOOK_DEFAULT_XSL_MAN DOCBOOK_DEFAULT_XSL_SLIDESPDF DOCBOOK_DEFAULT_XSL_SLIDESHTML @@ -212,6 +214,15 @@ current environment, if no other XSLT gets specified via keyword. + + + +The default XSLT file for the &b-link-DocbookEpub; builder within the +current environment, if no other XSLT gets specified via keyword. + + + + @@ -473,6 +484,27 @@ env.DocbookPdf('manual') + + + +A pseudo-Builder, providing a Docbook toolchain for EPUB output. + + +env = Environment(tools=['docbook']) +env.DocbookEpub('manual.epub', 'manual.xml') + + + +or simply + + +env = Environment(tools=['docbook']) +env.DocbookEpub('manual') + + + + + diff --git a/test/Docbook/basic/epub/epub.py b/test/Docbook/basic/epub/epub.py new file mode 100644 index 0000000..c819dd7 --- /dev/null +++ b/test/Docbook/basic/epub/epub.py @@ -0,0 +1,62 @@ +#!/usr/bin/env python +# +# Copyright (c) 2001-2010 The SCons Foundation +# +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, +# distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to +# the following conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +# + +""" +Test the EPUB builder. +""" + +import TestSCons + +test = TestSCons.TestSCons() + +try: + import libxml2 +except: + try: + import lxml + except: + test.skip_test('Cannot find installed Python binding for libxml2 or lxml, skipping test.\n') + +test.dir_fixture('image') + +# Normal invocation +test.run() +test.must_exist(test.workpath('manual.epub')) +test.must_exist(test.workpath('OEBPS','toc.ncx')) +test.must_exist(test.workpath('OEBPS','content.opf')) +test.must_exist(test.workpath('META-INF','container.xml')) + +# Cleanup +test.run(arguments='-c') +test.must_not_exist(test.workpath('manual.epub')) +test.must_not_exist(test.workpath('OEBPS')) +test.must_not_exist(test.workpath('META-INF')) + +test.pass_test() + +# Local Variables: +# tab-width:4 +# indent-tabs-mode:nil +# End: +# vim: set expandtab tabstop=4 shiftwidth=4: diff --git a/test/Docbook/basic/epub/image/SConstruct b/test/Docbook/basic/epub/image/SConstruct new file mode 100644 index 0000000..16a0699 --- /dev/null +++ b/test/Docbook/basic/epub/image/SConstruct @@ -0,0 +1,2 @@ +env = Environment(tools=['docbook']) +env.DocbookEpub('manual') diff --git a/test/Docbook/basic/epub/image/manual.xml b/test/Docbook/basic/epub/image/manual.xml new file mode 100644 index 0000000..ca12e0e --- /dev/null +++ b/test/Docbook/basic/epub/image/manual.xml @@ -0,0 +1,388 @@ + + + +
+ The SCons qt4 tool + + + + Dirk Baechle + + + 2010-12-06 + + +
+ Basics + + This tool can be used to compile Qt projects, designed for versions + 4.x.y and higher. It is not usable for Qt3 and older versions, since some + of the helper tools (moc, uic) + behave different. + +
+ Install + + Installing it, requires you to copy (or, even better: checkout) + the contents of the package's qt4 folder to + + + + /path_to_your_project/site_scons/site_tools/qt4, + if you need the Qt4 Tool in one project only, or + + + + ~/.scons/site_scons/site_tools/qt4, + for a system-wide installation under your current login. + + + + For more infos about this, please refer to + + + + the SCons User's Guide, chap. 17.7 "Where to put your custom + Builders and Tools" and + + + + the SCons Tools Wiki page at http://scons.org/wiki/ToolsIndex. + + +
+ +
+ How to activate + + For activating the tool "qt4", you have to add its name to the + Environment constructor, like this + + env = Environment(tools=['default','qt4']) + + + On its startup, the Qt4 tool tries to read the variable + QT4DIR from the current Environment and + os.environ. If it is not set, the value of + QTDIR (in Environment/os.environ) + is used as a fallback. + + So, you either have to explicitly give the path of your Qt4 + installation to the Environment with + + env['QT4DIR'] = '/usr/local/Trolltech/Qt-4.2.3' + + + or set the QT4DIR as environment variable in + your shell. +
+ +
+ Requirements + + Under Linux, "qt4" uses the system tool + pkg-config for automatically setting the required + compile and link flags of the single Qt4 modules (like QtCore, + QtGui,...). This means that + + + + you should have pkg-config installed, + and + + + + you additionally have to set + PKG_CONFIG_PATH in your shell environment, such + that it points to $QT4DIR/lib/pkgconfig (or + $QT4DIR/lib for some older versions). + + + + Based on these two environment variables + (QT4DIR and PKG_CONFIG_PATH), the + "qt4" tool initializes all QT4_* construction + variables listed in the Reference manual. This happens when the tool is + "detected" during Environment construction. As a consequence, the setup + of the tool gets a two-stage process, if you want to override the values + provided by your current shell settings: + + # Stage 1: create plain environment +qtEnv = Environment() +# Set new vars +qtEnv['QT4DIR'] = '/usr/local/Trolltech/Qt-4.2.3 +qtEnv['ENV']['PKG_CONFIG_PATH'] = '/usr/local/Trolltech/Qt-4.2.3/lib/pkgconfig' +# Stage 2: add qt4 tool +qtEnv.Tool('qt4') + +
+
+ +
+ Suggested boilerplate + + Based on the requirements above, we suggest a simple ready-to-go + setup as follows: + + SConstruct + + # Detect Qt version +qtdir = detectLatestQtDir() + +# Create base environment +baseEnv = Environment() +#...further customization of base env + +# Clone Qt environment +qtEnv = baseEnv.Clone() +# Set QT4DIR and PKG_CONFIG_PATH +qtEnv['ENV']['PKG_CONFIG_PATH'] = os.path.join(qtdir, 'lib/pkgconfig') +qtEnv['QT4DIR'] = qtdir +# Add qt4 tool +qtEnv.Tool('qt4') +#...further customization of qt env + +# Export environments +Export('baseEnv qtEnv') + +# Your other stuff... +# ...including the call to your SConscripts + + + In a SConscript + + # Get the Qt4 environment +Import('qtEnv') +# Clone it +env = qtEnv.clone() +# Patch it +env.Append(CCFLAGS=['-m32']) # or whatever +# Use it +env.StaticLibrary('foo', Glob('*.cpp')) + + + The detection of the Qt directory could be as simple as directly + assigning a fixed path + + def detectLatestQtDir(): + return "/usr/local/qt4.3.2" + + + or a little more sophisticated + + # Tries to detect the path to the installation of Qt with +# the highest version number +def detectLatestQtDir(): + if sys.platform.startswith("linux"): + # Simple check: inspect only '/usr/local/Trolltech' + paths = glob.glob('/usr/local/Trolltech/*') + if len(paths): + paths.sort() + return paths[-1] + else: + return "" + else: + # Simple check: inspect only 'C:\Qt' + paths = glob.glob('C:\\Qt\\*') + if len(paths): + paths.sort() + return paths[-1] + else: + return os.environ.get("QTDIR","") + +
+ +
+ A first project + + The following SConscript is for a simple project with some cxx + files, using the QtCore, QtGui and QtNetwork modules: + + Import('qtEnv') +env = qtEnv.Clone() +env.EnableQt4Modules([ + 'QtGui', + 'QtCore', + 'QtNetwork' + ]) +# Add your CCFLAGS and CPPPATHs to env here... + +env.Program('foo', Glob('*.cpp')) + +
+ +
+ MOC it up + + For the basic support of automocing, nothing needs to be done by the + user. The tool usually detects the Q_OBJECT macro and + calls the moc executable + accordingly. + + If you don't want this, you can switch off the automocing by + a + + env['QT4_AUTOSCAN'] = 0 + + + in your SConscript file. Then, you have to moc your files + explicitly, using the Moc4 builder. + + You can also switch to an extended automoc strategy with + + env['QT4_AUTOSCAN_STRATEGY'] = 1 + + + Please read the description of the + QT4_AUTOSCAN_STRATEGY variable in the Reference manual + for details. + + For debugging purposes, you can set the variable + QT4_DEBUG with + + env['QT4_DEBUG'] = 1 + + + which outputs a lot of messages during automocing. +
+ +
+ Forms (.ui) + + The header files with setup code for your GUI classes, are not + compiled automatically from your .ui files. You always + have to call the Uic4 builder explicitly like + + env.Uic4(Glob('*.ui')) +env.Program('foo', Glob('*.cpp')) + +
+ +
+ Resource files (.qrc) + + Resource files are not built automatically, you always have to add + the names of the .qrc files to the source list for your + program or library: + + env.Program('foo', Glob('*.cpp')+Glob('*.qrc')) + + + For each of the Resource input files, its prefix defines the name of + the resulting resource. An appropriate + -name option is added to the call of the + rcc executable by default. + + You can also call the Qrc4 builder explicitly as + + qrccc = env.Qrc4('foo') # ['foo.qrc'] -> ['qrc_foo.cc'] + + + or (overriding the default suffix) + + qrccc = env.Qrc4('myprefix_foo.cxx','foo.qrc') # -> ['qrc_myprefix_foo.cxx'] + + + and then add the resulting cxx file to the sources of your + Program/Library: + + env.Program('foo', Glob('*.cpp') + qrccc) + +
+ +
+ Translation files + + The update of the .ts files and the conversion to + binary .qm files is not done automatically. You have to + call the corresponding builders on your own. + + Example for updating a translation file: + + env.Ts4('foo.ts','.') # -> ['foo.ts'] + + + By default, the .ts files are treated as + precious targets. This means that they are not + removed prior to a rebuild, but simply get updated. Additionally, they do + not get cleaned on a scons -c. If you + want to delete the translation files on the + -c SCons command, you can set the + variable QT4_CLEAN_TS like this + + env['QT4_CLEAN_TS']=1 + + + Example for releasing a translation file, i.e. compiling it to a + .qm binary file: + + env.Qm4('foo') # ['foo.ts'] -> ['foo.qm'] + + + or (overriding the output prefix) + + env.Qm4('myprefix','foo') # ['foo.ts'] -> ['myprefix.qm'] + + + As an extension both, the Ts4() and Qm4 builder, support the + definition of multiple targets. So, calling + + env.Ts4(['app_en','app_de'], Glob('*.cpp')) + + + and + + env.Qm4(['app','copy'], Glob('*.ts')) + + + should work fine. + + Finally, two short notes about the support of directories for the + Ts4() builder. You can pass an arbitrary mix of cxx files and subdirs to + it, as in + + env.Ts4('app_en',['sub1','appwindow.cpp','main.cpp'])) + + + where sub1 is a folder that gets scanned + recursively for cxx files by lupdate. But like this, + you lose all dependency information for the subdir, i.e. if a file inside + the folder changes, the .ts file is not updated automatically! In this + case you should tell SCons to always update the target: + + ts = env.Ts4('app_en',['sub1','appwindow.cpp','main.cpp']) +env.AlwaysBuild(ts) + + + Last note: specifying the current folder + . as input to Ts4() and storing the + resulting .ts file in the same directory, leads to a dependency cycle! You + then have to store the .ts and .qm files outside of the current folder, or + use Glob('*.cpp')) instead. +
+
-- cgit v0.12