Hi,
this morning I wanted to edit the unsupported modules rst pages and
ended up going through the geotools docs build process for the first time.
Run mvn install in the docs module and saw sphinx process through 4
different documentation sets, building everything from scratch. 1 minute build.
Run mvn install again and it started over from stratch, again one minute!
Holy inefficient build Batman!
First observation:
- when you do mvn install in any java module it will recompile only the
files that changed since the last build, not _everything_
- if you want to recompile everything just do a mvn clean install instead
Found out this was due to the param given to sphinx, forcing it to
reinspect and re-evaluate everything. Oh boy, why why?
Removed those, got the build going down from 60+ seconds to 7-8
seconds. Much better, if I modify a single file it will rebuild just
that one.
Still, it is still a far cry away from the almost instant doc re-build we
have in GeoServer using makefiles.
Then noticed the packaging of the module was "jar", which resulted in
building a source jar nobody would end up using. Moved packaging
to pom, same result, one less jar around, one second less in the build.
Still, the thing is doing too much, if I want to work on the user docs
why insist on rebuilding everything else?
Refactored the pom and ant file to allow building a single sub-section
of the docs via a profile:
mvn install -Puser
Better, but still 6 second long build. Why oh why? Well, because maven
has a large startup time. But Ant doesn't, and most of the work is done
by Ant.
So refactored a little more the build.xml to be able to run it directly
if ant is available on the machine.
ant user
Buildfile: /home/aaime/devel/git-gt/docs/build.xml
init:
[echo] Build directory is /home/aaime/devel/git-gt/docs/target
and project version is 8.0-M0
user:
sphinx:
[echo] Running sphinx-build -D release=8.0-M0 -b html -d
"/home/aaime/devel/git-gt/docs/target/user/doctrees" .
"/home/aaime/devel/git-gt/docs/target/user/html"
[exec] Running Sphinx v1.0.7
[exec] loading pickled environment... done
[exec] building [html]: targets for 0 source files that are out of date
[exec] updating environment: 0 added, 0 changed, 0 removed
[exec] looking for now-outdated files... none found
[exec] no targets are out of date.
BUILD SUCCESSFUL
Total time: 0 seconds
Aaah, now we're talking. If one really wants to start fresh and
rebuild everything user related
instead just run "ant clean user", easy peasy.
Maven remains there for those that do not have Ant around and for the
main build, but whoever else
can enjoy a faster doc dev cycle with the modifications I've cooked.
Now, I did not commit them still because I don't know if there is a
specific reason for the current
build process.
Can people review and tell me if it's acceptable to go on and commit
the patch attached to this mail?
Cheers
Andrea
--
-------------------------------------------------------
Ing. Andrea Aime
GeoSolutions S.A.S.
Tech lead
Via Poggio alle Viti 1187
55054 Massarosa (LU)
Italy
phone: +39 0584 962313
fax: +39 0584 962313
http://www.geo-solutions.it
http://geo-solutions.blogspot.com/
http://www.youtube.com/user/GeoSolutionsIT
http://www.linkedin.com/in/andreaaime
http://twitter.com/geowolf
-------------------------------------------------------
diff --git a/docs/build.xml b/docs/build.xml
index 7ba63ec..d594bee 100644
--- a/docs/build.xml
+++ b/docs/build.xml
@@ -1,7 +1,7 @@
-<project name="docs" default="build">
+<project name="docs" default="full">
- <target name="build">
- <property environment="env"/>
+ <target name="init">
+ <property environment="env"/>
<condition property="sphinx.available">
<or>
<available file="sphinx-build" filepath="${env.PATH}"/>
@@ -22,53 +22,72 @@
</or>
</condition>
+ <condition property="build.directory" value="${build.directory}" else="${basedir}/target">
+ <isset property="build.directory" />
+ </condition>
+
+ <condition property="project.version" value="${project.version}" else="8.0-M0">
+ <isset property="project.version" />
+ </condition>
+
+ <echo message="Build directory is ${build.directory} and project version is ${project.version}"/>
+ </target>
+
+ <target name="clean" depends="init">
+ <delete includeemptydirs="true">
+ <fileset dir="${build.directory}" defaultexcludes="false">
+ <include name="**/" />
+ </fileset>
+ </delete>
+ </target>
+
+ <target name="index" depends="init">
<antcall target="sphinx-ignore-warnings">
<param name="id" value="index"/>
<param name="build" value="html"/>
- </antcall>
+ </antcall>
+ </target>
+ <target name="user" depends="init">
<antcall target="sphinx">
<param name="id" value="user" />
<param name="build" value="html" />
</antcall>
+ </target>
+ <target name="web" depends="init">
<antcall target="sphinx">
<param name="id" value="web"/>
<param name="build" value="html"/>
</antcall>
+ </target>
- <!-- uncomment for developers guide -->
+ <target name="developer" depends="init">
<antcall target="sphinx">
<param name="id" value="developer"/>
<param name="build" value="html"/>
</antcall>
- <!-- uncomment for pdf -->
- <!--antcall target="pdf">
- <param name="id" value="tutorial"/>
- <param name="build" value="pdf"/>
- </antcall-->
- <!--antcall target="latex">
- <param name="id" value="tutorial"/>
- <param name="build" value="latex"/>
- </antcall-->
</target>
+ <target name="full" depends="index,user,web,developer">
+ </target>
<target name="sphinx-ignore-warnings" if="sphinx.available">
<exec executable="sphinx-build" failonerror="true" dir="${basedir}/${id}">
- <arg line="-D release=${project.version} -a -E -b ${build} -d "${build.directory}/${id}/doctrees" . "${build.directory}/${id}/${build}""/>
+ <arg line="-D release=${project.version} -b ${build} -d "${build.directory}/${id}/doctrees" . "${build.directory}/${id}/${build}""/>
</exec>
</target>
<target name="sphinx" if="sphinx.available">
+ <echo message="Running sphinx-build -D release=${project.version} -b ${build} -d "${build.directory}/${id}/doctrees" . "${build.directory}/${id}/${build}""/>
<exec executable="sphinx-build" failonerror="true" dir="${basedir}/${id}">
- <arg line="-D release=${project.version} -a -W -E -b ${build} -d "${build.directory}/${id}/doctrees" . "${build.directory}/${id}/${build}""/>
+ <arg line="-D release=${project.version} -b ${build} -d "${build.directory}/${id}/doctrees" . "${build.directory}/${id}/${build}""/>
</exec>
</target>
<target name="latex" if="latex.available">
<exec executable="sphinx-build" failonerror="true" dir="${basedir}/${id}">
- <arg line="-D release=${project.version} -a -E -b latex -d "${build.directory}/${id}/doctrees" . "${build.directory}/${id}/${build}""/>
+ <arg line="-D release=${project.version} -b latex -d "${build.directory}/${id}/doctrees" . "${build.directory}/${id}/${build}""/>
</exec>
</target>
diff --git a/docs/pom.xml b/docs/pom.xml
index 0b5dd3c..4d45870 100644
--- a/docs/pom.xml
+++ b/docs/pom.xml
@@ -22,7 +22,7 @@
<!-- =========================================================== -->
<groupId>org.geotools</groupId>
<artifactId>docs</artifactId>
- <packaging>jar</packaging>
+ <packaging>pom</packaging>
<name>Geotools Documentation</name>
<description>GeoTools website, user and developer guides.</description>
@@ -224,7 +224,7 @@
<phase>compile</phase>
<configuration>
<tasks>
- <ant antfile="build.xml" dir="${basedir}" target="build">
+ <ant antfile="build.xml" dir="${basedir}" target="${target}">
<property name="build.directory" value="${build.directory}"/>
<!-- may be ${project.version} when tagged -->
<property name="project.version" value="8.0-M0"/>
@@ -240,4 +240,35 @@
</plugins>
</build>
+ <properties>
+ <target>full</target>
+ </properties>
+
+ <profiles>
+ <profile>
+ <id>index</id>
+ <properties>
+ <target>index</target>
+ </properties>
+ </profile>
+ <profile>
+ <id>user</id>
+ <properties>
+ <target>user</target>
+ </properties>
+ </profile>
+ <profile>
+ <id>web</id>
+ <properties>
+ <target>web</target>
+ </properties>
+ </profile>
+ <profile>
+ <id>developer</id>
+ <properties>
+ <target>developer</target>
+ </properties>
+ </profile>
+ </profiles>
+
</project>
------------------------------------------------------------------------------
Achieve unprecedented app performance and reliability
What every C/C++ and Fortran developer should know.
Learn how Intel has extended the reach of its next-generation tools
to help boost performance applications - inlcuding clusters.
http://p.sf.net/sfu/intel-dev2devmay
_______________________________________________
Geotools-devel mailing list
Geotools-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/geotools-devel
