http://git-wip-us.apache.org/repos/asf/polygene-website/blob/2d44da7d/content/java/develop/build-system.html ---------------------------------------------------------------------- diff --git a/content/java/develop/build-system.html b/content/java/develop/build-system.html index ec33119..b069472 100644 --- a/content/java/develop/build-system.html +++ b/content/java/develop/build-system.html @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Polygene⢠Build System</title><link rel="stylesheet" type="text/css" href="css/style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="" /><link rel="up" href="tutorials.html" title="Tutorials" /><link rel="prev" href="howto-invocation-annotation.html" title="Use @Invocation" /><link rel="next" href="community-docs.html" title="Polygene⢠Documentation" /> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Polygene⢠Build System</title><link rel="stylesheet" type="text/css" href="css/style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="" /><link rel="up" href="tutorials.html" title="Tutorials" /><link rel="prev" href="howto-invocation-annotation.html" title="Use @Invocation" /><link rel="next" href="community-docs.html" title="Polygene⢠Documentation" /> <!-- favicon --> @@ -66,75 +66,75 @@ })(); </script> - </head><body><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="logo"><a href="index.html"><img src="images/logo-standard.png" /></a></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="top-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl class="toc"><dt><span class="section"><a href="index.html#home">Polygeneâ¢</a></span></dt><dt><span class="section"><a href="intro.html">Introduction</a></span></dt><dt><span class="section"><span xmlns="" href="tutorials.html">Tutorials</span></span></dt><dt><span class="section"><a href="javadocs.html">Javadoc</a></span></dt><dt><span class="section"><a href="samples.html">Samples</a></span></dt><dt><span class="section"><a href="core.html">Core</a></span></dt><dt><span class="section"><a href="libraries.html">Libraries</a></span></dt><dt><span class="section"><a href="extensions.html">Extensions</a></span></dt><dt><span class="section"><a href="tools.html">Tools</a></span></dt><dt><span class="section"><a href= "glossary.html">Glossary </a></span></dt></dl></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="sub-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl class="toc"><dt><span class="section"><a href="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Polygene⢠in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Polygene⢠in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Polygene⢠in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-polygene.html">Depend on Polygeneâ¢</a></span></dt><dt><span class="section"><a href="howto-assemble-application.html">Assemble an Application</a></span></dt><dt><span class="section"><a href="tut-composites.html">Transient Composites Tutorial</a></span></dt><dt><span class="section"><a href="tut-services.html">Services Composites Tutorial</a></span></dt><dt>< span class="section"><a href="howto-contextual-fragments.html">Use contextual fragments</a></span></dt><dt><span class="section"><a href="howto-leverage-properties.html">Leverage Properties</a></span></dt><dt><span class="section"><a href="howto-create-constraint.html">Create a Constraint</a></span></dt><dt><span class="section"><a href="howto-create-concern.html">Create a Concern</a></span></dt><dt><span class="section"><a href="howto-create-sideeffect.html">Create a SideEffect</a></span></dt><dt><span class="section"><a href="howto-create-entity.html">Create an Entity</a></span></dt><dt><span class="section"><a href="howto-configure-service.html">Configure a Service</a></span></dt><dt><span class="section"><a href="howto-invocation-annotation.html">Use @Invocation</a></span></dt><dt><span class="section"><span xmlns="" href="build-system.html">Polygene⢠Build System</span></span></dt><dt><span class="section"><a href="community-docs.html">Polygene⢠Documentation</a></span></dt ><dt><span class="section"><a href="releasing-apache.html">Releasing >Polygeneâ¢</a></span></dt></dl></div></div><div class="section"><div >class="titlepage"><div><div><h3 class="title"><a >id="build-system"></a>Polygene⢠Build System</h3></div></div></div><p>This >tutorial is intended for developers who want to build the Polygene⢠SDK >themselves. + </head><body><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="logo"><a href="index.html"><img src="images/logo-standard.png" /></a></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="top-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="index.html#home">Polygeneâ¢</a></span></dt><dt><span class="section"><a href="intro.html">Introduction</a></span></dt><dt><span class="section"><span xmlns="" href="tutorials.html">Tutorials</span></span></dt><dt><span class="section"><a href="javadocs.html">Javadoc</a></span></dt><dt><span class="section"><a href="samples.html">Samples</a></span></dt><dt><span class="section"><a href="core.html">Core</a></span></dt><dt><span class="section"><a href="libraries.html">Libraries</a></span></dt><dt><span class="section"><a href="extensions.html">Extensions</a></span></dt><dt><span class="section"><a href="tools.html">Tools</a></span></dt><dt><span class="section"><a href="glossary.ht ml">Glossary </a></span></dt></dl></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="sub-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Polygene⢠in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Polygene⢠in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Polygene⢠in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-polygene.html">Depend on Polygeneâ¢</a></span></dt><dt><span class="section"><a href="howto-assemble-application.html">Assemble an Application</a></span></dt><dt><span class="section"><a href="tut-composites.html">Transient Composites Tutorial</a></span></dt><dt><span class="section"><a href="tut-services.html">Services Composites Tutorial</a></span></dt><dt><span class="section"><a href="howto-contextual-fragments.html">Use contextual fragments</a></span></dt><dt><span class="section"><a href="howto-leverage-properties.html">Leverage Properties</a></span></dt><dt><span class="section"><a href="howto-create-constraint.html">Create a Constraint</a></span></dt><dt><span class="section"><a href="howto-create-concern.html">Create a Concern</a></span></dt><dt><span class="section"><a href="howto-create-sideeffect.html">Create a SideEffect</a></span></dt><dt><span class="section"><a href="howto-create-entity.html">Create an Entity</a></span></dt><dt><span class="section"><a href="howto-configure-service.html">Configure a Service</a></span></dt><dt><span class="section"><a href="howto-invocation-annotation.html">Use @Invocation</a></span></dt><dt><span class="section"><span xmlns="" href="build-system.html">Polygene⢠Build System</span></span></dt><dt><span class="section"><a href="community-docs.html">Polygene⢠Documentation</a></span></dt><dt><span class="sectio n"><a href="releasing-apache.html">Releasing Polygeneâ¢</a></span></dt></dl></div></div><div class="section" title="Polygene⢠Build System"><div class="titlepage"><div><div><h3 class="title"><a id="build-system"></a>Polygene⢠Build System</h3></div></div></div><p>This tutorial is intended for developers who want to build the Polygene⢠SDK themselves. It describe the Polygene⢠SDK Build System from compilation to publication of artifacts for consumption by other applications.</p><p>If instead you want to setup your project build system to depend on modules of the Polygene⢠SDK see the -<a class="link" href="howto-depend-on-polygene.html" title="Depend on Polygeneâ¢">dedicated tutorial</a>.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_gradle"></a>Gradle</h4></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>All major Java IDEs have great Gradle support. +<a class="link" href="howto-depend-on-polygene.html" title="Depend on Polygeneâ¢">dedicated tutorial</a>.</p><div class="section" title="Gradle"><div class="titlepage"><div><div><h4 class="title"><a id="_gradle"></a>Gradle</h4></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>All major Java IDEs have great Gradle support. Visit the <a class="ulink" href="https://www.gradle.org/resources"; target="_top">Gradle</a> website to learn how to import the Polygene⢠SDK build into your favorite IDE.</p></div><p>Polygene⢠community migrated away from Maven after several years of frustration, especially around release management, versioning and cross-module dependency resolution issues, in Feb 2011. The tool of choice is now Gradle, and it doesnât require any installation, there are <code class="literal">gradlew</code> and <code class="literal">gradlew.bat</code> in the root folder of the Polygene⢠SDK that will bootstrap Gradle if not done so already.</p><p>If you are new to Gradle, you should keep the <a class="ulink" href="https://gradle.org/docs"; target="_top">documentation</a> at hands.</p><p>Build System configuration is done through Gradle properties. This can be done in many ways, see -<a class="ulink" href="https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_properties_and_system_properties"; target="_top">Gradle properties and system properties</a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_the_wrapper"></a>The Wrapper</h4></div></div></div><p><code class="literal">gradlew</code> and <code class="literal">gradlew.bat</code> scripts that can be found at the root of the Polygene sources is <span class="strong"><strong>The Wrapper</strong></span>. +<a class="ulink" href="https://docs.gradle.org/current/userguide/build_environment.html#sec:gradle_properties_and_system_properties"; target="_top">Gradle properties and system properties</a>.</p></div><div class="section" title="The Wrapper"><div class="titlepage"><div><div><h4 class="title"><a id="_the_wrapper"></a>The Wrapper</h4></div></div></div><p><code class="literal">gradlew</code> and <code class="literal">gradlew.bat</code> scripts that can be found at the root of the Polygene sources is <span class="strong"><strong>The Wrapper</strong></span>. Any build invocation starts from this script. It will download the Gradle distribution version required by the build. -See the <a class="ulink" href="https://docs.gradle.org/current/userguide/gradle_wrapper.html"; target="_top">Gradle Wrapper</a> documentation for more details.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_main_tasks"></a>Main tasks</h4></div></div></div><p>The Polygene⢠SDK project has tasks that work with the whole SDK.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +See the <a class="ulink" href="https://docs.gradle.org/current/userguide/gradle_wrapper.html"; target="_top">Gradle Wrapper</a> documentation for more details.</p></div><div class="section" title="Main tasks"><div class="titlepage"><div><div><h4 class="title"><a id="_main_tasks"></a>Main tasks</h4></div></div></div><p>The Polygene⢠SDK project has tasks that work with the whole SDK.</p><div class="variablelist"><dl><dt><span class="term"> <code class="literal">./gradlew downloadDependencies</code> </span></dt><dd></dd></dl></div><p>Resolve, download and cache all needed dependencies. -Useful to go offline.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +Useful to go offline.</p><div class="variablelist"><dl><dt><span class="term"> <code class="literal">./gradlew</code> </span></dt><dd></dd></dl></div><p>The default build, triggered when running gradle without any command line arguments, compiles the code and run the -tests, but nothing else. A quick way to check that nothing broke.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +tests, but nothing else. A quick way to check that nothing broke.</p><div class="variablelist"><dl><dt><span class="term"> <code class="literal">./gradlew clean</code> -</span></dt><dd></dd></dl></div><p>Clean up of all build output and restore the code base to a fresh state.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +</span></dt><dd></dd></dl></div><p>Clean up of all build output and restore the code base to a fresh state.</p><div class="variablelist"><dl><dt><span class="term"> <code class="literal">./gradlew assemble</code> </span></dt><dd></dd></dl></div><p>Produces all the archives, javadocs, manuals and website content. -Global output is generated into <code class="literal">distributions/build</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +Global output is generated into <code class="literal">distributions/build</code>.</p><div class="variablelist"><dl><dt><span class="term"> <code class="literal">./gradlew check</code> </span></dt><dd></dd></dl></div><p>Run the tests and other checks like checkstyle. -Global reports are generated in <code class="literal">reports/build/reports</code>.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +Global reports are generated in <code class="literal">reports/build/reports</code>.</p><div class="variablelist"><dl><dt><span class="term"> <code class="literal">./gradlew build</code> -</span></dt><dd></dd></dl></div><p>Equivalent to <code class="literal">./gradlew assemble check</code></p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +</span></dt><dd></dd></dl></div><p>Equivalent to <code class="literal">./gradlew assemble check</code></p><div class="variablelist"><dl><dt><span class="term"> <code class="literal">./gradlew checkDistributions</code> </span></dt><dd></dd></dl></div><p>Run global checks against the assembled distributions. -Can take a while.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"> +Can take a while.</p><div class="variablelist"><dl><dt><span class="term"> <code class="literal">./gradlew install</code> </span></dt><dd></dd></dl></div><p>Is roughly the same as Mavenâs install goal. It produces the test reports, javadocs and installs all the Jars into the local disk repository, for consumption -by other applications.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_other_tasks"></a>Other tasks</h4></div></div></div><p>In addition to that, some submodules have specific tasks. +by other applications.</p></div><div class="section" title="Other tasks"><div class="titlepage"><div><div><h4 class="title"><a id="_other_tasks"></a>Other tasks</h4></div></div></div><p>In addition to that, some submodules have specific tasks. To see all available tasks, issue the following command:</p><pre class="programlisting brush: bash">./gradlew tasks</pre><p>All available tasks from all modules of the SDK are shown. If you want to narrow your exploration to submodules use the following:</p><pre class="programlisting brush: bash">./gradlew :test:performance:tasks ./gradlew :release:tasks</pre><p>These examples will respectively output all gradle tasks available in the <code class="literal">:tests:performance</code> module where you should find -the <code class="literal">performanceTest</code> task that runs the Polygene⢠performance test suite and the <code class="literal">:release</code> module tasks.</p><p><code class="literal">tasks</code> itself is a task, in the same way we can target module(s) with tasks, e.g.:</p><pre class="programlisting brush: bash">./gradlew :core:check :libraries:alarm:check</pre></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_versions"></a>Versions</h4></div></div></div><p>By default, the build system produces a "zero build". +the <code class="literal">performanceTest</code> task that runs the Polygene⢠performance test suite and the <code class="literal">:release</code> module tasks.</p><p><code class="literal">tasks</code> itself is a task, in the same way we can target module(s) with tasks, e.g.:</p><pre class="programlisting brush: bash">./gradlew :core:check :libraries:alarm:check</pre></div><div class="section" title="Versions"><div class="titlepage"><div><div><h4 class="title"><a id="_versions"></a>Versions</h4></div></div></div><p>By default, the build system produces a "zero build". It means that there is no version assigned to the build, and a "0" is used in the produced artifacts. This is due to our disagreement (with Maven community) that the "next" version name/number is known prior to the release. This is in our opinion a delayed decision. To build a particular version, you specify a <code class="literal">version</code> property on the command-line, like</p><pre class="programlisting brush: bash">./gradlew -Dversion=2.0-FLAVOUR install</pre><p>If a <code class="literal">version</code> property is not defined, the build system will refuse to make a release and upload. -It will also try hard to do less and not get in your way.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_tests"></a>Tests</h4></div></div></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>See the <a class="ulink" href="https://builds.apache.org/view/P/view/Polygene/"; target="_top">Polygene⢠Continuous Integration</a> for current tests results</p></div><p>Unit and integration tests are located near the code under test. -Youâll find theses tests across the whole SDK.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_unit_tests_requiring_external_services"></a>Unit tests requiring external services</h5></div></div></div><p>Among unit tests, some require an external service to be run. -For example, the Redis EntityStore extension requires an actual Redis server to run its tests.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The HTML test reports generated by Gradle shows skipped tests.</p></div><p>Testing against external services is automated using Docker and is enabled automatically if a running Docker service +It will also try hard to do less and not get in your way.</p></div><div class="section" title="Tests"><div class="titlepage"><div><div><h4 class="title"><a id="_tests"></a>Tests</h4></div></div></div><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>See the <a class="ulink" href="https://builds.apache.org/view/P/view/Polygene/"; target="_top">Polygene⢠Continuous Integration</a> for current tests results</p></div><p>Unit and integration tests are located near the code under test. +Youâll find theses tests across the whole SDK.</p><div class="section" title="Unit tests requiring external services"><div class="titlepage"><div><div><h5 class="title"><a id="_unit_tests_requiring_external_services"></a>Unit tests requiring external services</h5></div></div></div><p>Among unit tests, some require an external service to be run. +For example, the Redis EntityStore extension requires an actual Redis server to run its tests.</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The HTML test reports generated by Gradle shows skipped tests.</p></div><p>Testing against external services is automated using Docker and is enabled automatically if a running Docker service is reachable. The build creates the necessary Docker images and start/stop containers around the tests.</p><p>On Linux it should work out of the box.</p><p>The simplest way to get this running on other systems (macOS and Windows) is to use <code class="literal">docker-machine</code> to create a development Docker virtual machine where all images will be built and containers started:</p><pre class="programlisting brush: bash">docker-machine create dev docker-machine start dev eval $(docker-machine env dev)</pre><p>The last stanza set environment variables for Docker to use the newly created Docker virtual machine.</p><p>If you want to run the Docker containers in a remote machine, simply set the <code class="literal">DOCKER_HOST</code> and <code class="literal">DOCKER_CERT_PATH</code> environment variables to something sensible for your setup.</p><p>If you want to forcibly skip all Docker related work, set the <code class="literal">skipDocker</code> Gradle property by e.g. appending -<code class="literal">-PskipDocker</code> to your Gradle command line.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_performance_tests"></a>Performance tests</h5></div></div></div><p>Performance tests provide performance measurements for typical Polygene⢠use cases. -They are not part of the default build and are located in the <code class="literal">tests/performance</code> directory of the SDK.</p><p>They can be run with the following Gradle command:</p><pre class="programlisting brush: bash">./gradlew :tests:performance:performanceTest</pre><p>Results will then be available in the test reports.</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_documentation_generation"></a>Documentation generation</h4></div></div></div><p>The build generates a documentation minisite:</p><pre class="programlisting brush: bash">./gradlew :manual:assemble</pre><p>Output is in <code class="literal">~/manual/build/docs/website</code>.</p><p>Youâll need Asciidoc and docbook-xsl installed.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_build_for_releases"></a>Build for releases</h4></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class ="title">Important</h3><p>Remember that if a <code class="literal">version</code> property is not defined, the build system will refuse to make a release and upload.</p></div><p>The Polygene⢠SDK build system is setup for an easy release process. +<code class="literal">-PskipDocker</code> to your Gradle command line.</p></div><div class="section" title="Performance tests"><div class="titlepage"><div><div><h5 class="title"><a id="_performance_tests"></a>Performance tests</h5></div></div></div><p>Performance tests provide performance measurements for typical Polygene⢠use cases. +They are not part of the default build and are located in the <code class="literal">tests/performance</code> directory of the SDK.</p><p>They can be run with the following Gradle command:</p><pre class="programlisting brush: bash">./gradlew :tests:performance:performanceTest</pre><p>Results will then be available in the test reports.</p></div></div><div class="section" title="Documentation generation"><div class="titlepage"><div><div><h4 class="title"><a id="_documentation_generation"></a>Documentation generation</h4></div></div></div><p>The build generates a documentation minisite:</p><pre class="programlisting brush: bash">./gradlew :manual:assemble</pre><p>Output is in <code class="literal">~/manual/build/docs/website</code>.</p><p>Youâll need Asciidoc and docbook-xsl installed.</p></div><div class="section" title="Build for releases"><div class="titlepage"><div><div><h4 class="title"><a id="_build_for_releases"></a>Build for releases</h4></div></div></div><div class="important " title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Remember that if a <code class="literal">version</code> property is not defined, the build system will refuse to make a release and upload.</p></div><p>The Polygene⢠SDK build system is setup for an easy release process. This is very useful to the Polygene⢠Core Team but can also be useful to third parties that want to cut a in-house release. In this regard, we try to make every aspect of the release process usable for such cases.</p><p>The following sections describe various aspects of the release process. -By default you need to have a proper PGP setup, see below.</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_release_criteria"></a>Release Criteria</h5></div></div></div><p>The Polygene⢠SDK modules are of varying maturity level and we try to maintain a STATUS (<code class="literal">dev-status.xml</code>) file indicating +By default you need to have a proper PGP setup, see below.</p><div class="section" title="Release Criteria"><div class="titlepage"><div><div><h5 class="title"><a id="_release_criteria"></a>Release Criteria</h5></div></div></div><p>The Polygene⢠SDK modules are of varying maturity level and we try to maintain a STATUS (<code class="literal">dev-status.xml</code>) file indicating how good the codebase, documentation and unit tests are for each of the modules. This is highly subjective and potentially different individuals will judge this differently, but at least it gives a ballpark idea of the situation for our users.</p><p>The Polygene⢠SDK build system use the values from the <code class="literal">dev-status.xml</code> files to filter out non-releasable modules out for the <code class="literal">javadocs</code> and <code class="literal">uploadArchives</code> root project tasks. Moreover, the <code class="literal">release</code> task ensure that no releasable module depends on module(s) that donât fit the release criteria -and throw a detailed exception if need be.</p><p>This can be relaxed by adding <code class="literal">-x checkReleaseSpec</code> arguments to gradle invocation.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_signing"></a>Signing</h5></div></div></div><p>Artifact signing is done using PGP. +and throw a detailed exception if need be.</p><p>This can be relaxed by adding <code class="literal">-x checkReleaseSpec</code> arguments to gradle invocation.</p></div><div class="section" title="Signing"><div class="titlepage"><div><div><h5 class="title"><a id="_signing"></a>Signing</h5></div></div></div><p>Artifact signing is done using PGP. You need to provide Gradle the following properties, <code class="literal">~/.gradle/gradle.properties</code> is a good place:</p><pre class="literallayout">signing.keyId=FB751943 signing.password=foobar -signing.secretKeyRingFile=/home/foo/.gnupg/secring.gpg</pre><p>You can skip the signing process by adding <code class="literal">-x signArchives</code> arguments to gradle invocation.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_artifact_upload"></a>Artifact Upload</h5></div></div></div><p>Artifact upload behavior depends on the version assigned to the build.</p><p>By default RELEASES are signed, SNAPSHOTS are not. +signing.secretKeyRingFile=/home/foo/.gnupg/secring.gpg</pre><p>You can skip the signing process by adding <code class="literal">-x signArchives</code> arguments to gradle invocation.</p></div><div class="section" title="Artifact Upload"><div class="titlepage"><div><div><h5 class="title"><a id="_artifact_upload"></a>Artifact Upload</h5></div></div></div><p>Artifact upload behavior depends on the version assigned to the build.</p><p>By default RELEASES are signed, SNAPSHOTS are not. Signing can be turned on or off by setting the <code class="literal">uploadSigned</code> property to false.</p><p>By default RELEASES must satisfy ReleaseSpecification, SNAPSHOT donât. ReleaseSpecification usage can be turned on or off by setting the <code class="literal">uploadReleaseSpec</code> property to false.</p><p>By default RELEASES and SNAPHOTS are uploaded using HTTP. Used Wagon can be overriden by setting the <code class="literal">uploadWagon</code> property.</p><p>By default RELEASES and SNAPSHOTS are uploaded to the Apache Nexus.
http://git-wip-us.apache.org/repos/asf/polygene-website/blob/2d44da7d/content/java/develop/community-docs.html ---------------------------------------------------------------------- diff --git a/content/java/develop/community-docs.html b/content/java/develop/community-docs.html index 006967c..db99d29 100644 --- a/content/java/develop/community-docs.html +++ b/content/java/develop/community-docs.html @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8" standalone="no"?> -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Polygene⢠Documentation</title><link rel="stylesheet" type="text/css" href="css/style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.79.1" /><link rel="home" href="index.html" title="" /><link rel="up" href="tutorials.html" title="Tutorials" /><link rel="prev" href="build-system.html" title="Polygene⢠Build System" /><link rel="next" href="releasing-apache.html" title="Releasing Polygeneâ¢" /> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd";><html xmlns="http://www.w3.org/1999/xhtml";><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>Polygene⢠Documentation</title><link rel="stylesheet" type="text/css" href="css/style.css" /><meta name="generator" content="DocBook XSL Stylesheets V1.76.1" /><link rel="home" href="index.html" title="" /><link rel="up" href="tutorials.html" title="Tutorials" /><link rel="prev" href="build-system.html" title="Polygene⢠Build System" /><link rel="next" href="releasing-apache.html" title="Releasing Polygeneâ¢" /> <!-- favicon --> @@ -66,14 +66,14 @@ })(); </script> - </head><body><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="logo"><a href="index.html"><img src="images/logo-standard.png" /></a></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="top-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl class="toc"><dt><span class="section"><a href="index.html#home">Polygeneâ¢</a></span></dt><dt><span class="section"><a href="intro.html">Introduction</a></span></dt><dt><span class="section"><span xmlns="" href="tutorials.html">Tutorials</span></span></dt><dt><span class="section"><a href="javadocs.html">Javadoc</a></span></dt><dt><span class="section"><a href="samples.html">Samples</a></span></dt><dt><span class="section"><a href="core.html">Core</a></span></dt><dt><span class="section"><a href="libraries.html">Libraries</a></span></dt><dt><span class="section"><a href="extensions.html">Extensions</a></span></dt><dt><span class="section"><a href="tools.html">Tools</a></span></dt><dt><span class="section"><a href= "glossary.html">Glossary </a></span></dt></dl></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="sub-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl class="toc"><dt><span class="section"><a href="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Polygene⢠in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Polygene⢠in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Polygene⢠in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-polygene.html">Depend on Polygeneâ¢</a></span></dt><dt><span class="section"><a href="howto-assemble-application.html">Assemble an Application</a></span></dt><dt><span class="section"><a href="tut-composites.html">Transient Composites Tutorial</a></span></dt><dt><span class="section"><a href="tut-services.html">Services Composites Tutorial</a></span></dt><dt>< span class="section"><a href="howto-contextual-fragments.html">Use contextual fragments</a></span></dt><dt><span class="section"><a href="howto-leverage-properties.html">Leverage Properties</a></span></dt><dt><span class="section"><a href="howto-create-constraint.html">Create a Constraint</a></span></dt><dt><span class="section"><a href="howto-create-concern.html">Create a Concern</a></span></dt><dt><span class="section"><a href="howto-create-sideeffect.html">Create a SideEffect</a></span></dt><dt><span class="section"><a href="howto-create-entity.html">Create an Entity</a></span></dt><dt><span class="section"><a href="howto-configure-service.html">Configure a Service</a></span></dt><dt><span class="section"><a href="howto-invocation-annotation.html">Use @Invocation</a></span></dt><dt><span class="section"><a href="build-system.html">Polygene⢠Build System</a></span></dt><dt><span class="section"><span xmlns="" href="community-docs.html">Polygene⢠Documentation</span></span></dt ><dt><span class="section"><a href="releasing-apache.html">Releasing >Polygeneâ¢</a></span></dt></dl></div></div><div class="section"><div >class="titlepage"><div><div><h3 class="title"><a >id="community-docs"></a>Polygene⢠>Documentation</h3></div></div></div><p>The documents use the asciidoc format, >see:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li >class="listitem"> + </head><body><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="logo"><a href="index.html"><img src="images/logo-standard.png" /></a></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="top-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="index.html#home">Polygeneâ¢</a></span></dt><dt><span class="section"><a href="intro.html">Introduction</a></span></dt><dt><span class="section"><span xmlns="" href="tutorials.html">Tutorials</span></span></dt><dt><span class="section"><a href="javadocs.html">Javadoc</a></span></dt><dt><span class="section"><a href="samples.html">Samples</a></span></dt><dt><span class="section"><a href="core.html">Core</a></span></dt><dt><span class="section"><a href="libraries.html">Libraries</a></span></dt><dt><span class="section"><a href="extensions.html">Extensions</a></span></dt><dt><span class="section"><a href="tools.html">Tools</a></span></dt><dt><span class="section"><a href="glossary.ht ml">Glossary </a></span></dt></dl></div></div><div xmlns="" xmlns:exsl="http://exslt.org/common"; class="sub-nav"><div xmlns="http://www.w3.org/1999/xhtml"; class="toc"><dl><dt><span class="section"><a href="tutorials.html#_overview">Overview</a></span></dt><dt><span class="section"><a href="two-minutes-intro.html">Polygene⢠in 2 minutes</a></span></dt><dt><span class="section"><a href="ten-minutes-intro.html">Polygene⢠in 10 minutes</a></span></dt><dt><span class="section"><a href="thirty-minutes-intro.html">Polygene⢠in 30 minutes</a></span></dt><dt><span class="section"><a href="howto-depend-on-polygene.html">Depend on Polygeneâ¢</a></span></dt><dt><span class="section"><a href="howto-assemble-application.html">Assemble an Application</a></span></dt><dt><span class="section"><a href="tut-composites.html">Transient Composites Tutorial</a></span></dt><dt><span class="section"><a href="tut-services.html">Services Composites Tutorial</a></span></dt><dt><span class="section"><a href="howto-contextual-fragments.html">Use contextual fragments</a></span></dt><dt><span class="section"><a href="howto-leverage-properties.html">Leverage Properties</a></span></dt><dt><span class="section"><a href="howto-create-constraint.html">Create a Constraint</a></span></dt><dt><span class="section"><a href="howto-create-concern.html">Create a Concern</a></span></dt><dt><span class="section"><a href="howto-create-sideeffect.html">Create a SideEffect</a></span></dt><dt><span class="section"><a href="howto-create-entity.html">Create an Entity</a></span></dt><dt><span class="section"><a href="howto-configure-service.html">Configure a Service</a></span></dt><dt><span class="section"><a href="howto-invocation-annotation.html">Use @Invocation</a></span></dt><dt><span class="section"><a href="build-system.html">Polygene⢠Build System</a></span></dt><dt><span class="section"><span xmlns="" href="community-docs.html">Polygene⢠Documentation</span></span></dt><dt><span class="sectio n"><a href="releasing-apache.html">Releasing Polygeneâ¢</a></span></dt></dl></div></div><div class="section" title="Polygene⢠Documentation"><div class="titlepage"><div><div><h3 class="title"><a id="community-docs"></a>Polygene⢠Documentation</h3></div></div></div><p>The documents use the asciidoc format, see:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> <a class="ulink" href="http://www.methods.co.nz/asciidoc/"; target="_top">Aciidoc Reference</a> </li><li class="listitem"> <a class="ulink" href="http://powerman.name/doc/asciidoc"; target="_top">AsciiDoc cheatsheet</a> -</li></ul></div><p>The cheatsheet is really useful!</p><p>You need to install <code class="literal">asciidoc</code> and <code class="literal">docbook-xsl</code>.</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="community-docs-overall-flow"></a>Overall Flow</h4></div></div></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>To generate the website locally use <code class="literal">./gradlew website</code>. Output is in <code class="literal">~/manual/build/docs/website</code>.</p></div><p>Each (sub)project has its own documentation, in <span class="emphasis"><em>src/docs/</em></span> and all the Asciidoc documents have the <code class="literal">.txt</code> file extension.</p><p>The documents can use code snippets which will extract code from the project. This is preferred way to include +</li></ul></div><p>The cheatsheet is really useful!</p><p>You need to install <code class="literal">asciidoc</code> and <code class="literal">docbook-xsl</code>.</p><div class="section" title="Overall Flow"><div class="titlepage"><div><div><h4 class="title"><a id="community-docs-overall-flow"></a>Overall Flow</h4></div></div></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>To generate the website locally use <code class="literal">./gradlew website</code>. Output is in <code class="literal">~/manual/build/docs/website</code>.</p></div><p>Each (sub)project has its own documentation, in <span class="emphasis"><em>src/docs/</em></span> and all the Asciidoc documents have the <code class="literal">.txt</code> file extension.</p><p>The documents can use code snippets which will extract code from the project. This is preferred way to include source code in the documentation, since any refactoring will be reflected in the documentation.</p><p>The above files are all consumed by the build of the manual (by adding them as dependencies). To get content included in the manual, it has to be explicitly included by a document in the manual as well.</p><p>The whole documentation set is generated from the <span class="emphasis"><em>*manual*</em></span> module in the SDK, and we are currently only creating the website. -The User Guide and Reference Manual are future projects.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_headings_and_document_structure"></a>Headings and document structure</h4></div></div></div><p>Each document starts over with headings from level zero (the document title). +The User Guide and Reference Manual are future projects.</p></div><div class="section" title="Headings and document structure"><div class="titlepage"><div><div><h4 class="title"><a id="_headings_and_document_structure"></a>Headings and document structure</h4></div></div></div><p>Each document starts over with headings from level zero (the document title). Each document should have an id. In some cases sections in the document need to have idâs as well, this depends on where they fit in the overall structure. To be able to link to content, it has to have an id. @@ -85,9 +85,9 @@ attribute is used when including the document inside of another document.</p><p> === Subsubheading === -content here ...</pre><p>Asciidoc comes with one more syntax for headings, but in this project itâs not used.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_writing"></a>Writing</h4></div></div></div><p>Try to put one sentence on each line. +content here ...</pre><p>Asciidoc comes with one more syntax for headings, but in this project itâs not used.</p></div><div class="section" title="Writing"><div class="titlepage"><div><div><h4 class="title"><a id="_writing"></a>Writing</h4></div></div></div><p>Try to put one sentence on each line. Lines without empty lines between them still belongs to the same paragraph. -This makes it easy to move content around, and also easy to spot (too) long sentences.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_gotchas"></a>Gotchas</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> +This makes it easy to move content around, and also easy to spot (too) long sentences.</p></div><div class="section" title="Gotchas"><div class="titlepage"><div><div><h4 class="title"><a id="_gotchas"></a>Gotchas</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> A chapter canât be empty. (the build will fail on the docbook xml validity check) </li><li class="listitem"> The document title should be "underlined" by the same @@ -100,8 +100,8 @@ Always leave a blank line at the end of documents As <code class="literal">{}</code> are used for Asciidoc attributes, everything inside will be treated as an attribute. What you have to do is to escape the opening brace: <code class="literal">\{</code>. If you donât, the braces and the text inside them will be removed without any warning being issued! -</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_links"></a>Links</h4></div></div></div><p>To link to other parts of the manual the id of the target is used. -This is how such a reference looks:</p><pre class="programlisting brush: plain"><<community-docs-overall-flow>></pre><p>Which will render like: <a class="xref" href="community-docs.html#community-docs-overall-flow" title="Overall Flow">Documentation Flow</a></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Just write "see <<target-id>>" and similar, thatâs enough in most cases.</p></div><p>If you need to link to another document with your own link text, this is what to do:</p><pre class="programlisting brush: plain"><<target-id, link text that fits in the context>></pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Having lots of linked text may work well in a web context but is a pain in print, and we aim for both!</p></div><p>External links are added like this:</p><pre class="programlisting brush: plain">https://polygene.apache.org/[Link text here]</pre><p>Which renders like: <a class="ulink" href="https://polygene.apache.org/"; target="_top">Link text here</a></p><p>For short links it may be better not to add a link text, just do:</p><pre class="programlisting brush: plain">https://polygene.apache.org/</pre><p>Which renders like: <a class="ulink" href="https://polygene.apache.org/"; target="_top">https://polygene.apache.org/</a></p><p>Itâs ok to have a dot right after the URL, it wonât be part of the link.</p><pre class="programlisting brush: plain">https://polygene.apache.org/.</pre><p>Which renders like: <a class="ulink" href="https://polygene.apache.org/"; target="_top">https://polygene.apache.org/</a>.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_text_formatting"></a>Text Formatting</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> +</li></ul></div></div><div class="section" title="Links"><div class="titlepage"><div><div><h4 class="title"><a id="_links"></a>Links</h4></div></div></div><p>To link to other parts of the manual the id of the target is used. +This is how such a reference looks:</p><pre class="programlisting brush: plain"><<community-docs-overall-flow>></pre><p>Which will render like: <a class="xref" href="community-docs.html#community-docs-overall-flow" title="Overall Flow">Documentation Flow</a></p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Just write "see <<target-id>>" and similar, thatâs enough in most cases.</p></div><p>If you need to link to another document with your own link text, this is what to do:</p><pre class="programlisting brush: plain"><<target-id, link text that fits in the context>></pre><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Having lots of linked text may work well in a web context but is a pain in print, and we aim for both!</p></div><p>External links are added like this:</p><pre class="programlisting brush: plain">https://polyg ene.apache.org/[Link text here]</pre><p>Which renders like: <a class="ulink" href="https://polygene.apache.org/"; target="_top">Link text here</a></p><p>For short links it may be better not to add a link text, just do:</p><pre class="programlisting brush: plain">https://polygene.apache.org/</pre><p>Which renders like: <a class="ulink" href="https://polygene.apache.org/"; target="_top">https://polygene.apache.org/</a></p><p>Itâs ok to have a dot right after the URL, it wonât be part of the link.</p><pre class="programlisting brush: plain">https://polygene.apache.org/.</pre><p>Which renders like: <a class="ulink" href="https://polygene.apache.org/"; target="_top">https://polygene.apache.org/</a>.</p></div><div class="section" title="Text Formatting"><div class="titlepage"><div><div><h4 class="title"><a id="_text_formatting"></a>Text Formatting</h4></div></div></div><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> <span class="strong"><strong>Bold</strong></span> - just donât do it, the editor in charge is likely to remove it anyhow! </li><li class="listitem"> _Italics_ is rendered as <span class="emphasis"><em>Italics</em></span> @@ -111,14 +111,14 @@ _Italics_ is rendered as <span class="emphasis"><em>Italics</em></span> `command` is rendered as <code class="literal">command</code> (typically used for command-line) </li><li class="listitem"> 'my/path/' is rendered as <span class="emphasis"><em>my/path/</em></span> (used for file names and paths) -</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_admonitions"></a>Admonitions</h4></div></div></div><p>These are very useful and should be used where appropriate. -Choose from the following (write all caps and no, we canât easily add new ones):</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Note.</p></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Tip.</p></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Important</p></div><div class="caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>Caution</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Warning</p></div><p>Hereâs how itâs done:</p><pre class="programlisting brush: plain">NOTE: Note.</pre><p>A multiline variation:</p><pre class="programlisting brush: plain">[TIP] +</li></ul></div></div><div class="section" title="Admonitions"><div class="titlepage"><div><div><h4 class="title"><a id="_admonitions"></a>Admonitions</h4></div></div></div><p>These are very useful and should be used where appropriate. +Choose from the following (write all caps and no, we canât easily add new ones):</p><div class="note" title="Note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Note.</p></div><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Tip.</p></div><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p>Important</p></div><div class="caution" title="Caution" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Caution</h3><p>Caution</p></div><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Warning</p></div><p>Hereâs how itâs done:</p><pre class="programlisting brush: plain">NOTE: Note.</pre><p>A multiline variation:</p><pre class="programlisting brush: plain">[TIP] Tiptext. -Line 2.</pre><p>Which is rendered as:</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Tiptext. -Line 2.</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_images"></a>Images</h4></div></div></div><div class="important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p><span class="emphasis"><em>All images in the entire manual share the same namespace.</em></span></p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_images_files"></a>Images Files</h5></div></div></div><p>To include an image file, make sure it resides in the <span class="emphasis"><em>images/</em></span> directory relative to the document youâre including it from. +Line 2.</pre><p>Which is rendered as:</p><div class="tip" title="Tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>Tiptext. +Line 2.</p></div></div><div class="section" title="Images"><div class="titlepage"><div><div><h4 class="title"><a id="_images"></a>Images</h4></div></div></div><div class="important" title="Important" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Important</h3><p><span class="emphasis"><em>All images in the entire manual share the same namespace.</em></span></p></div><div class="section" title="Images Files"><div class="titlepage"><div><div><h5 class="title"><a id="_images_files"></a>Images Files</h5></div></div></div><p>To include an image file, make sure it resides in the <span class="emphasis"><em>images/</em></span> directory relative to the document youâre including it from. Then go:</p><pre class="programlisting brush: plain">image::logo-standard.png[]</pre><p>Which is rendered as:</p><div class="informalfigure"><a class="ulink" href="images/logo-standard.png" target="_top"> <span class="inlinemediaobject"><img src="images/logo-standard.png" alt="logo-standard.png" /></span> -</a></div><p>Please note that the <span class="emphasis"><em>images/</em></span> directory is added automatically and not part of the link.</p><p>There are also global resources, residing in <span class="emphasis"><em>manual/src/resources</em></span>, which will be copied to the root of the documentation.</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_code_snippets"></a>Code Snippets</h4></div></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_import_from_codebase"></a>Import from codebase</h5></div></div></div><p>Most source code that is included in the documentation should be extract via <code class="literal">SNIPPET</code> markers and then included in document with;</p><pre class="programlisting brush: plain"> [snippet,java] +</a></div><p>Please note that the <span class="emphasis"><em>images/</em></span> directory is added automatically and not part of the link.</p><p>There are also global resources, residing in <span class="emphasis"><em>manual/src/resources</em></span>, which will be copied to the root of the documentation.</p></div></div><div class="section" title="Code Snippets"><div class="titlepage"><div><div><h4 class="title"><a id="_code_snippets"></a>Code Snippets</h4></div></div></div><div class="section" title="Import from codebase"><div class="titlepage"><div><div><h5 class="title"><a id="_import_from_codebase"></a>Import from codebase</h5></div></div></div><p>Most source code that is included in the documentation should be extract via <code class="literal">SNIPPET</code> markers and then included in document with;</p><pre class="programlisting brush: plain"> [snippet,java] ----------- source=tutorials/introduction/tenminutes/src/main/java/org/apache/polygene/demo/tenminute/OrderEntity.java tag=mainClass @@ -149,7 +149,7 @@ public interface OrderEntity </pre><p>Note that 1. The START and END doesnât need to be matching. 1. The AsciiDoc plugin will remove the <span class="emphasis"><em>START SNIPPET</em></span> and <span class="emphasis"><em>END SNIPPET</em></span> lines. -1. If you have more than one START/END section with the same tag, the plugin will insert a "[â¦snipâ¦]" for the excluded lines.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_explicitly_defined_in_the_document"></a>Explicitly defined in the document</h5></div></div></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Use this kind of code snippets as little as possible. +1. If you have more than one START/END section with the same tag, the plugin will insert a "[â¦snipâ¦]" for the excluded lines.</p></div><div class="section" title="Explicitly defined in the document"><div class="titlepage"><div><div><h5 class="title"><a id="_explicitly_defined_in_the_document"></a>Explicitly defined in the document</h5></div></div></div><div class="warning" title="Warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Use this kind of code snippets as little as possible. They are well known to get out of sync with reality after a while.</p></div><p>This is how to do it:</p><pre class="programlisting brush: plain"> [source,java] ---- HashMap<String,String> result = new HashMap<String,String>(); @@ -163,7 +163,7 @@ public interface OrderEntity { if( !"".equals( name ) ) result.put( name, value ); - }</pre></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a id="_source_code_highlighting"></a>Source code Highlighting</h5></div></div></div><p>If thereâs no suitable syntax highlighter, just omit the language: <code class="literal">[source]</code>.</p><p>Currently the following syntax highlighters are enabled:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> + }</pre></div><div class="section" title="Source code Highlighting"><div class="titlepage"><div><div><h5 class="title"><a id="_source_code_highlighting"></a>Source code Highlighting</h5></div></div></div><p>If thereâs no suitable syntax highlighter, just omit the language: <code class="literal">[source]</code>.</p><p>Currently the following syntax highlighters are enabled:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> Bash </li><li class="listitem"> Groovy @@ -179,9 +179,9 @@ Ruby Scala </li><li class="listitem"> XML -</li></ul></div><p>For other highlighters we could add see <a class="ulink" href="http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/"; target="_top">http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/</a>.</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_attributes"></a>Attributes</h4></div></div></div><p>Common attributes you can use in documents:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> +</li></ul></div><p>For other highlighters we could add see <a class="ulink" href="http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/"; target="_top">http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/</a>.</p></div></div><div class="section" title="Attributes"><div class="titlepage"><div><div><h4 class="title"><a id="_attributes"></a>Attributes</h4></div></div></div><p>Common attributes you can use in documents:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> </li><li class="listitem"> -</li></ul></div><p>These can substitute part of URLs that point to for example APIdocs or source code.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a id="_toolchain"></a>Toolchain</h4></div></div></div><p>Useful links when configuring the docbook toolchain:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> +</li></ul></div><p>These can substitute part of URLs that point to for example APIdocs or source code.</p></div><div class="section" title="Toolchain"><div class="titlepage"><div><div><h4 class="title"><a id="_toolchain"></a>Toolchain</h4></div></div></div><p>Useful links when configuring the docbook toolchain:</p><div class="itemizedlist"><ul class="itemizedlist"><li class="listitem"> <a class="ulink" href="http://www.methods.co.nz/asciidoc"; target="_top">http://www.methods.co.nz/asciidoc</a> </li><li class="listitem"> <a class="ulink" href="http://powerman.name/doc/asciidoc"; target="_top">http://powerman.name/doc/asciidoc</a>
