Author: buildbot
Date: Mon Apr 18 17:11:49 2022
New Revision: 1079219
Log:
Production update by buildbot for tapestry
Modified:
websites/production/tapestry/content/building-tapestry-from-source.html
websites/production/tapestry/content/cache/main.pageCache
Modified:
websites/production/tapestry/content/building-tapestry-from-source.html
==============================================================================
--- websites/production/tapestry/content/building-tapestry-from-source.html
(original)
+++ websites/production/tapestry/content/building-tapestry-from-source.html Mon
Apr 18 17:11:49 2022
@@ -142,7 +142,7 @@
<!-- /// Content Start -->
<div id="content">
- <div id="ConfluenceContent"><p>This is a guide to
building Tapestry itself from source code. This is primarily of interest to
Tapestry <em>contributors</em>, rather than Tapestry
<em>users</em>.</p><p>Although Tapestry <em>users</em> are free to use any
build mechanism for their own projects (and first class Maven support is
provided), to build Tapestry itself from source you will use
Gradle.</p><p>Note: Both command line and Eclipse Gradle IDE/EGit instructions
are given here. Generally you'll want to chose approach one or the other,
rather than mixing them.</p><h2
id="BuildingTapestryfromSource-Prerequisites">Prerequisites</h2><ul><li>Install
a <strong>Java JDK</strong> (Sun/Oracle, not OpenJDK), version 1.7 (just to
prevent VU#225657, see: <a class="external-link"
href="http://www.kb.cert.org/vuls/id/225657";
rel="nofollow">http://www.kb.cert.org/vuls/id/225657</a>), or version 1.8 for
Tapestry 5.5 and later.</li><li>Install an <strong>IDE</strong> (IDE
A IntelliJ is recommended (and free to Tapestry committers), but Eclipse will
also work. NetBeans is reported to work as
well.</li><li><strong>Firefox</strong>: For Tapestry 5.4.x and earlier, install
Firefox browser <a class="external-link"
href="https://ftp.mozilla.org/pub/firefox/releases/42.0/";
rel="nofollow">version 42</a> or earlier, needed for the integration tests
(because newer versions require a newer version of Selenium than Tapestry's
Java version requirements allow).</li><li><s>Set the Firefox browser's
"preferred language" to English (en), because some tests will otherwise
fail.</s> (Fixed; see <a class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-2413";>TAP5-2413</a>)</li><li>Install
a <strong>Git</strong> client<ul><li>Command-line users: <a
class="external-link" href="http://git-scm.com/downloads";
rel="nofollow">http://git-scm.com/downloads</a></li><li>Eclipse users: install
EGit from the Eclipse Marketplace, then in In Window > Preferences >
; Team > Git, set your "Default repository folder" (e.g. <code>~/git</code>
or <code>%HOME%\git</code>). Note that for Eclipse 4.4 (Luna) and later Git
support is built in.</li></ul></li><li>Install <strong>Gradle</strong>
1.0-milestone-3 or newer (or a Gradle plugin to your IDE),<ul><li>Command-line
users: nothing to do (Tapestry's Gradle wrapper, gradlew, will download Gradle
automatically on first use).</li><li>Eclipse users: Install Gradle IDE (aka
Gradle Integration for Eclipse), from the Eclipse Marketplace. Note that for
Eclipse 4.6 (Neon) and later, Gradle support is built
in.</li></ul></li></ul><h2
id="BuildingTapestryfromSource-GettingStarted">Getting Started</h2><p>Please
read <a class="external-link"
href="https://git-wip-us.apache.org/";>https://git-wip-us.apache.org/</a>
first.</p><p>Windows users (especialy EGit users) should probably set the
core.autocrlf config setting to <code>false</code> so that local diffs won't
highlight line ending differences.</p><h3 id="Bu
ildingTapestryfromSource-ClonetheRepository">Clone the Repository</h3><p>Clone
Tapestry from the Git repo:</p><ul><li><p>Command-line git users:</p><div
class="table-wrap"><table class="table table-bordered
table-responsive"><tbody><tr><td colspan="1" rowspan="1"
class="confluenceTd"><p>Non Committers:</p></td><td colspan="1" rowspan="1"
class="confluenceTd"><p>git clone</p><a class="external-link"
href="http://git-wip-us.apache.org/repos/asf/tapestry-5.git";>http://git-wip-us.apache.org/repos/asf/tapestry-5.git</a></td></tr><tr><td
colspan="1" rowspan="1" class="confluenceTd"><p>Committers:</p></td><td
colspan="1" rowspan="1" class="confluenceTd"><p>git clone</p><a
class="external-link"
href="https://git-wip-us.apache.org/repos/asf/tapestry-5.git";>https://git-wip-us.apache.org/repos/asf/tapestry-5.git</a></td></tr></tbody></table></div></li><li>Eclipse
EGit users:<ul><li>Switch to Git perspective; then copy one of the URLs above
into paste buffer</li><li>Right-click > Paste repos
itory path or URI. This will bring up the Clone Git Repository
dialog.</li><li>Committers: make sure Protocol is https, and enter your Apache
commiter LDAP user name & password</li><li>click Next.</li><li>Select the
branches you're interested in (e.g 5.3 and master), click Next</li><li>Select
Directory to where you want the project source code (e.g.
<code>~/git/tapestry-5</code> or
<code>%HOME%\git\tapestry-5</code>)</li><li>Select whichever "Initial Branch"
you're interested in (e.g. master)</li><li>Set "Remote name" to "origin" (the
default)</li><li><strong>VERY IMPORTANT</strong>: uncheck the "Import all
existing projects" checkbox (we'll do this using Gradle, below)</li><li>Click
Finish. (Be patient; the clone operation might take a few
minutes.)</li></ul></li></ul><h3
id="BuildingTapestryfromSource-GradlePreparation">Gradle
Preparation</h3><ul><li>Command-line gradle users only:<ul><li>If you're using
Eclipse but <strong>not</strong> Gradle IDE do <code>./gradlew eclipse</c
ode></li><li>The command-line Gradle's eclipse plugin doesn't include the
provided project dependencies; you need to add them manually (Java Build Path
> Projects > Add tapestry-test). The plugin also generates a root eclipse
project, so you'll need to delete the ".project" file in the root folder, and
then you can import all Tapestry sub-projects at
once.</li></ul></li><li>Eclipse Gradle IDE users:<ul><li>Switch to Java (or
JEE) perspective and right-click > Import... > Gradle > Gradle Project
> Next.</li><li>Set the "Root folder" to where you put your Tapestry source
in the previous section (e.g. <code>~/git/tapestry-5</code> or
<code>%Home%\git\tapestry-5</code>)</li><li>Click <code>Build Model. When it
completes, s</code>elect the top-level (the top-level module and all
sub-modules).</li><li>Be sure the "Enable dependency management" and "Create
workingset 'tapestry-5' checkboxes are checked.</li><li>Click
<code>Finish</code>. (Be patient; the import operation
might take a few minutes.)</li></ul></li><li>Eclipse EGit users: Do a Git
"Share" on the project:<ul><li>Still in the Java (or JEE) perspective, select
all of the Tapestry projects (top-level and sub-modules) and right-click >
Team > Share Project... > Git > Next > Ensure all are selected,
click <code>Finish</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-Antlr">Antlr</h3><p>The
<code>tapestry-core</code> project will initially have errors because of
missing Java classes that are produced by ANTLR the first time the project is
built. To fix this:</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click on
the <code>build.gradle</code> file within tapestry-core and click Run As >
"Gradle build...", check <strong>only</strong> the generateGrammarSource task,
and change the "Name" field to something like "tapestry-core antlr", then click
Apply and Run.</li><li>When it's finished, the antlr-generated classes (e.g.
PropertyExpressionLexer.java) will be in c
reated in $buildDir/generated-sources/antlr/, but Eclipse doesn't yet know
about that path. To fix that, right click on the <code>tapestry-core</code>
project > Properties > Java Build Path > Source > Add Folder >
find <code>tapestry-core/build/generated-sources/antlr</code> and check the
checkbox next to it, then click <code>OK</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-CoffeeScript">CoffeeScript</h3><p>If you want to
run tests from within Eclipse, Tapestry will complain that it won't find
certain JavaScript files that normally are generated during compile time from
their Coffeescript sources. In order to generate the JavaScript files you need
to have Coffeescript installed and in your path. Simply install <a
class="external-link" href="http://nodejs.org/download/";
rel="nofollow">Node.js</a> and afterwards run <code>npm install -g
coffee-script</code>. The installation should take care of
everything.</p><ul><li>Eclipse Gradle IDE users:<ul><li>Righ
t click on the <code>build.gradle</code> file within tapestry-core and click
Run As > "Gradle build...", check <strong>only</strong> the
tapestry-core:compileCoffeeScript and tapestry-core:compileTestCoffeeScript
tasks, and change the "Name" field to something like "tapestry-core
coffeescript", then click Apply and Run.</li><li>When it's finished, the
coffeescript-generated JavaScript files (e.g. t5-core-dom-jquery.js) will be in
created in $buildDir/generated-sources/compiled-coffeescript/ and
$buildDir/generated-sources/compiled-test-coffeescript/, but Eclipse doesn't
yet know about that path. To fix that, right click on the
<code>tapestry-core</code> project > Properties > Java Build Path >
Source > Add Folder > find
<code>tapestry-core/build/generated-sources/compiled-coffeescript</code> and
<code>tapestry-core/build/generated-sources/compiled-test-coffeescript</code>
and check the checkbox next to it, then click
<code>OK</code>.</li></ul></li></ul><h3 id="Buil
dingTapestryfromSource-GenerateCoffeeScriptandAntlrfilesautomaticallywhenchanged">Generate
CoffeeScript and Antlr files automatically when changed</h3><p>If you want to
have Eclipse compile the JavaScript files and lexer classes from their
Coffeescript sources and Antlr files automatically when they change, you can do
that by configuring an additional builder for the <code>tapestry-core</code>
project:</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click on the
<code>tapestry-core</code> project and select properties.</li><li>Select the
"Builders" entry from the list on the left and click "New.." in the right
panel.</li><li>Select "Program" and click "Ok".</li><li>Give the program a
meaningful name, e.g. "compile coffeescript and antlr".</li><li>Switch to the
"Main" tab.</li><li>For "Location:" click "Browse Workspace..." and select
gradlew (for Mac/Linux) or <code>gradlew.bat (for Windows)</code> in the
Tapestry root project. If the root project is called "tapestry-5" the entry
should look similar to "${workspace_loc:/tapestry-5/gradlew.bat}".</li><li>For
"Working Directory:" click "Browse Workspace..." and select the Tapestry root
project.</li><li>For "Arguments:" enter
<code>tapestry-core:generateGrammarSource tapestry-core:compileCoffeeScript
tapestry-core:compileTestCoffeeScript</code></li><li>Switch to the "Build
Options" tab.</li><li>Make sure that only "Allocate Console", "After a
"Clean"", "During manual builds", "During auto builds" and "Specify working set
of relevant resources" are checked.</li><li>Click "Specify
Resources...".</li><li>From the "tapestry-core" project select
"src/main/antlr", "src/main/coffeescript", and
"src/test/coffeescript".</li><li>Click "Finish".</li><li>Click
"OK".</li><li>Click "OK".</li></ul></li></ul><h3
id="BuildingTapestryfromSource-Building">Building</h3><p>You can build
individual modules, or (from the root folder) build
everything.</p><ul><li>Command-line users: *( "gradlew" is the gradle wrapper
shell script (gra
dlew) or batch file (gradlew.bat) found in the root folder of the Tapestry
source.<ul><li><code>./gradlew build</code></li></ul></li><li>Eclipse Gradle
IDE users:<ul><li>Right click on the top-level project (or any sub-project) and
select Run As > Gradle Build..., which starts an External Tools
Configuration dialog box. Enter a reasonable name, select the tasks you want to
run (for example, tapestry-core/install), and click Run.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-SeleniumSetup">Selenium Setup</h3><p>It is
necessary that you have a compatible version of Firefox installed.  On a
Mac, you should install it in ~/Applications (rather than
/Applications).</p><p>You should modify your ~/.bash_profile (or equivalent),
to add ~/Applications/Firefox.app/Contents/MacOS to the PATH variable.</p><h3
id="BuildingTapestryfromSource-RunningIndividualTests">Running Individual
Tests</h3><p>Eclipse users:</p><ul><li>Install the <a class="external-link"
href="http://testng.or
g/doc/eclipse.html" rel="nofollow">TestNG plugin</a> to allow running of
individual TestNG unit tests from within in Eclipse.</li><li>Right-click on any
test class and select Run As >TestNG Test</li></ul><p>Command-line
users:</p><ul><li>./gradlew -Dtest.single=myclassname</li><li>./gradlew
-Dtest.single=myclassname.mymethod</li></ul><p>where myclassname is the test
class, such as FormTest</p><p>The Tapestry integration tests will repeatedly
start up a Firefox browser.</p><ul><li>Ensure that your environment will allow
a connection to <a class="external-link" href="https://localhost:9090";
rel="nofollow">https://localhost:9090</a></li></ul><h3
id="BuildingTapestryfromSource-SkippingTests">Skipping Tests</h3><p>Running the
Tapestry integration tests can take 10 minutes or more (mostly because of
Selenium tests, which repeatedly start and stop the Firefox browser), so you
won't want to run them every time you try a change.</p><ul><li>Command-line
users:<ul><li><code>To build while s
kipping all tests: ./gradlew build -x test</code></li><li>You can skip tests
on a specific module by adding a colon and the module name. For example:
<code>-x test:tapestry-ioc</code></li></ul></li><li>Eclipse Gradle IDE
users:<ul><li>In your External Tools Configuration, add the same -x test option
as above at Arguments > Program Arguments.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-RunningtheIntegrationTestAppsManually">Running
the Integration Test Apps Manually</h3><p>The Tapestry source includes several
small web apps that are used by the automated Selenium integration tests. You
can also run these apps manually to try out nearly every browser-visible aspect
of Tapestry. Just invoke the corresponding Gradle tasks. This is mainly useful
when debugging failing selenium tests.</p><ul><li>Command-line
users:<ul><li>./gradlew runTestApp1</li></ul></li><li>Eclipse users:<ul><li>Use
the run-jetty-run plugin in Eclipse, with the context directory selected from
among the <c
ode>test</code> context directories. For example, in the tapestry-core module,
right click on the /src/test/app1 (or app2, etc) folder, and select Run As >
Run Jetty, then open your browser to <a class="external-link"
href="http://localhost:8080/tapestry-core";
rel="nofollow">http://localhost:8080/tapestry-core</a></li></ul></li></ul><p>The
integration test apps are:</p><ul><li>activationctx – used
by tapestry-core integration tests</li><li>activationctx2 –
used by tapestry-core integration tests</li><li>app0 – used
only by the tapestry-hibernate integration tests</li><li><strong>app1
– used by most of the tapestry-core integration
tests</strong></li><li>app2 – used by tapestry-core integration
tests (HTTPS)app3 – used by tapestry-core integration
tests</li><li>app4 – used by tapestry-core integration
tests</li><li>app5 – used by tapestry-core integration
tests</li><li>
<em>appfolder</em>  – used by tapestry-core integration
tests</li><li>cluster – used by tapestry-core integration
tests</li><li>linktrans – used by tapestry-core integration
tests</li><li>symbolparam – used by tapestry-core integration
tests</li><li>(...and a few others not yet documented, and without Gradle tasks
yet. Search for web.xml files in the Tapestry source.)</li></ul><h3
id="BuildingTapestryfromSource-MakingCodeChanges">Making Code
Changes</h3><p>Once you have cloned or pulled the latest changes to your local
Git repository, you can start working on it. Whenever you make some changes to
the codebase, it's good to have a related issue filed in JIRA and to use a
similarly named branch in your local Git repository. For example, to create a
branch for an issue with the key TAP5-123:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
+ <div id="ConfluenceContent"><p>This is a guide to
building Tapestry itself from source code. This is primarily of interest to
Tapestry <em>contributors</em>, rather than Tapestry
<em>users</em>.</p><p>Although Tapestry <em>users</em> are free to use any
build mechanism for their own projects (and first class Maven support is
provided), to build Tapestry itself from source you will use
Gradle.</p><p>Note: Both command line and Eclipse Gradle IDE/EGit instructions
are given here. Generally you'll want to chose approach one or the other,
rather than mixing them.</p><h2
id="BuildingTapestryfromSource-Prerequisites">Prerequisites</h2><ul><li>Install
a <strong>Java JDK</strong> (Sun/Oracle, not OpenJDK), version 1.7 (just to
prevent VU#225657, see: <a class="external-link"
href="http://www.kb.cert.org/vuls/id/225657";
rel="nofollow">http://www.kb.cert.org/vuls/id/225657</a>), or version 1.8 for
Tapestry 5.5 and later.</li><li>Install an <strong>IDE</strong> (IDE
A IntelliJ is recommended (and free to Tapestry committers), but Eclipse will
also work. NetBeans is reported to work as
well.</li><li><strong>Firefox</strong>: For Tapestry 5.4.x and earlier, install
Firefox browser <a class="external-link"
href="https://ftp.mozilla.org/pub/firefox/releases/42.0/";
rel="nofollow">version 42</a> or earlier, needed for the integration tests
(because newer versions require a newer version of Selenium than Tapestry's
Java version requirements allow).</li><li><s>Set the Firefox browser's
"preferred language" to English (en), because some tests will otherwise
fail.</s> (Fixed; see <a class="external-link"
href="https://issues.apache.org/jira/browse/TAP5-2413";>TAP5-2413</a>)</li><li>Install
a <strong>Git</strong> client<ul><li>Command-line users: <a
class="external-link" href="http://git-scm.com/downloads";
rel="nofollow">http://git-scm.com/downloads</a></li><li>Eclipse users: install
EGit from the Eclipse Marketplace, then in In Window > Preferences >
; Team > Git, set your "Default repository folder" (e.g. <code>~/git</code>
or <code>%HOME%\git</code>). Note that for Eclipse 4.4 (Luna) and later Git
support is built in.</li></ul></li><li>Install <strong>Gradle</strong>
1.0-milestone-3 or newer (or a Gradle plugin to your IDE),<ul><li>Command-line
users: nothing to do (Tapestry's Gradle wrapper, gradlew, will download Gradle
automatically on first use).</li><li>Eclipse users: Install Gradle IDE (aka
Gradle Integration for Eclipse), from the Eclipse Marketplace. Note that for
Eclipse 4.6 (Neon) and later, Gradle support is built
in.</li></ul></li></ul><h2
id="BuildingTapestryfromSource-GettingStarted">Getting Started</h2><p>Please
read <a class="external-link"
href="https://gitbox.apache.org";>https://gitbox.apache.org</a>
first.</p><p>Windows users (especialy EGit users) should probably set the
core.autocrlf config setting to <code>false</code> so that local diffs won't
highlight line ending differences.</p><h3 id="BuildingTape
stryfromSource-ClonetheRepository">Clone the Repository</h3><p>Clone Tapestry
from the Git repo:</p><ul><li><p>Command-line git users: <code>git clone
https://gitbox.apache.org/repos/asf/tapestry-5.git</code></p></li><li>Eclipse
EGit users:<ul><li>Switch to Git perspective; then copy the URL above into
paste buffer</li><li>Right-click > Paste repository path or URI. This will
bring up the Clone Git Repository dialog.</li><li>Committers: make sure
Protocol is https, and enter your Apache commiter LDAP user name &
password</li><li>click Next.</li><li>Select the branches you're interested in
(e.g 5.3 and master), click Next</li><li>Select Directory to where you want the
project source code (e.g. <code>~/git/tapestry-5</code> or
<code>%HOME%\git\tapestry-5</code>)</li><li>Select whichever "Initial Branch"
you're interested in (e.g. master)</li><li>Set "Remote name" to "origin" (the
default)</li><li><strong>VERY IMPORTANT</strong>: uncheck the "Import all
existing projects" c
heckbox (we'll do this using Gradle, below)</li><li>Click Finish. (Be patient;
the clone operation might take a few minutes.)</li></ul></li></ul><h3
id="BuildingTapestryfromSource-GradlePreparation">Gradle
Preparation</h3><ul><li>Command-line gradle users only:<ul><li>If you're using
Eclipse but <strong>not</strong> Gradle IDE do <code>./gradlew
eclipse</code></li><li>The command-line Gradle's eclipse plugin doesn't include
the provided project dependencies; you need to add them manually (Java Build
Path > Projects > Add tapestry-test). The plugin also generates a root
eclipse project, so you'll need to delete the ".project" file in the root
folder, and then you can import all Tapestry sub-projects at
once.</li></ul></li><li>Eclipse Gradle IDE users:<ul><li>Switch to Java (or
JEE) perspective and right-click > Import... > Gradle > Gradle Project
> Next.</li><li>Set the "Root folder" to where you put your Tapestry source
in the previous section (e.g. <code>~/git/tap
estry-5</code> or <code>%Home%\git\tapestry-5</code>)</li><li>Click
<code>Build Model. When it completes, s</code>elect the top-level (the
top-level module and all sub-modules).</li><li>Be sure the "Enable dependency
management" and "Create workingset 'tapestry-5' checkboxes are
checked.</li><li>Click <code>Finish</code>. (Be patient; the import operation
might take a few minutes.)</li></ul></li><li>Eclipse EGit users: Do a Git
"Share" on the project:<ul><li>Still in the Java (or JEE) perspective, select
all of the Tapestry projects (top-level and sub-modules) and right-click >
Team > Share Project... > Git > Next > Ensure all are selected,
click <code>Finish</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-Antlr">Antlr</h3><p>The
<code>tapestry-core</code> project will initially have errors because of
missing Java classes that are produced by ANTLR the first time the project is
built. To fix this:</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click o
n the <code>build.gradle</code> file within tapestry-core and click Run As
> "Gradle build...", check <strong>only</strong> the generateGrammarSource
task, and change the "Name" field to something like "tapestry-core antlr", then
click Apply and Run.</li><li>When it's finished, the antlr-generated classes
(e.g. PropertyExpressionLexer.java) will be in created in
$buildDir/generated-sources/antlr/, but Eclipse doesn't yet know about that
path. To fix that, right click on the <code>tapestry-core</code> project >
Properties > Java Build Path > Source > Add Folder > find
<code>tapestry-core/build/generated-sources/antlr</code> and check the checkbox
next to it, then click <code>OK</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-CoffeeScript">CoffeeScript</h3><p>If you want to
run tests from within Eclipse, Tapestry will complain that it won't find
certain JavaScript files that normally are generated during compile time from
their Coffeescript sources. In
order to generate the JavaScript files you need to have Coffeescript installed
and in your path. Simply install <a class="external-link"
href="http://nodejs.org/download/"; rel="nofollow">Node.js</a> and afterwards
run <code>npm install -g coffee-script</code>. The installation should take
care of everything.</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click on
the <code>build.gradle</code> file within tapestry-core and click Run As >
"Gradle build...", check <strong>only</strong> the
tapestry-core:compileCoffeeScript and tapestry-core:compileTestCoffeeScript
tasks, and change the "Name" field to something like "tapestry-core
coffeescript", then click Apply and Run.</li><li>When it's finished, the
coffeescript-generated JavaScript files (e.g. t5-core-dom-jquery.js) will be in
created in $buildDir/generated-sources/compiled-coffeescript/ and
$buildDir/generated-sources/compiled-test-coffeescript/, but Eclipse doesn't
yet know about that path. To fix that, right click on the <
code>tapestry-core</code> project > Properties > Java Build Path >
Source > Add Folder > find
<code>tapestry-core/build/generated-sources/compiled-coffeescript</code> and
<code>tapestry-core/build/generated-sources/compiled-test-coffeescript</code>
and check the checkbox next to it, then click
<code>OK</code>.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-GenerateCoffeeScriptandAntlrfilesautomaticallywhenchanged">Generate
CoffeeScript and Antlr files automatically when changed</h3><p>If you want to
have Eclipse compile the JavaScript files and lexer classes from their
Coffeescript sources and Antlr files automatically when they change, you can do
that by configuring an additional builder for the <code>tapestry-core</code>
project:</p><ul><li>Eclipse Gradle IDE users:<ul><li>Right click on the
<code>tapestry-core</code> project and select properties.</li><li>Select the
"Builders" entry from the list on the left and click "New.." in the right
panel.</li><li>Sele
ct "Program" and click "Ok".</li><li>Give the program a meaningful name, e.g.
"compile coffeescript and antlr".</li><li>Switch to the "Main" tab.</li><li>For
"Location:" click "Browse Workspace..." and select gradlew (for Mac/Linux) or
<code>gradlew.bat (for Windows)</code> in the Tapestry root project. If the
root project is called "tapestry-5" the entry should look similar to
"${workspace_loc:/tapestry-5/gradlew.bat}".</li><li>For "Working Directory:"
click "Browse Workspace..." and select the Tapestry root project.</li><li>For
"Arguments:" enter <code>tapestry-core:generateGrammarSource
tapestry-core:compileCoffeeScript
tapestry-core:compileTestCoffeeScript</code></li><li>Switch to the "Build
Options" tab.</li><li>Make sure that only "Allocate Console", "After a
"Clean"", "During manual builds", "During auto builds" and "Specify working set
of relevant resources" are checked.</li><li>Click "Specify
Resources...".</li><li>From the "tapestry-core" project select
"src/main/antlr", "
src/main/coffeescript", and "src/test/coffeescript".</li><li>Click
"Finish".</li><li>Click "OK".</li><li>Click "OK".</li></ul></li></ul><h3
id="BuildingTapestryfromSource-Building">Building</h3><p>You can build
individual modules, or (from the root folder) build
everything.</p><ul><li>Command-line users:*( "gradlew" is the gradle wrapper
shell script (gradlew) or batch file (gradlew.bat) found in the root folder of
the Tapestry source.<ul><li><code>./gradlew
build</code></li></ul></li><li>Eclipse Gradle IDE users:<ul><li>Right click on
the top-level project (or any sub-project) and select Run As > Gradle
Build..., which starts an External Tools Configuration dialog box. Enter a
reasonable name, select the tasks you want to run (for example,
tapestry-core/install), and click Run.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-SeleniumSetup">Selenium Setup</h3><p>It is
necessary that you have a compatible version of Firefox installed.  On a
Mac, you should install it in
~/Applications (rather than /Applications).</p><p>You should modify your
~/.bash_profile (or equivalent), to add
~/Applications/Firefox.app/Contents/MacOS to the PATH variable.</p><h3
id="BuildingTapestryfromSource-RunningIndividualTests">Running Individual
Tests</h3><p>Eclipse users:</p><ul><li>Install the <a class="external-link"
href="http://testng.org/doc/eclipse.html"; rel="nofollow">TestNG plugin</a> to
allow running of individual TestNG unit tests from within in
Eclipse.</li><li>Right-click on any test class and select Run As >TestNG
Test</li></ul><p>Command-line users:</p><ul><li>./gradlew
-Dtest.single=myclassname</li><li>./gradlew
-Dtest.single=myclassname.mymethod</li></ul><p>where myclassname is the test
class, such as FormTest</p><p>The Tapestry integration tests will repeatedly
start up a Firefox browser.</p><ul><li>Ensure that your environment will allow
a connection to <a class="external-link" href="https://localhost:9090";
rel="nofollow">https://localhost:9090</a>
</li></ul><h3 id="BuildingTapestryfromSource-SkippingTests">Skipping
Tests</h3><p>Running the Tapestry integration tests can take 10 minutes or more
(mostly because of Selenium tests, which repeatedly start and stop the Firefox
browser), so you won't want to run them every time you try a
change.</p><ul><li>Command-line users:<ul><li><code>To build while skipping all
tests: ./gradlew build -x test</code></li><li>You can skip tests on a specific
module by adding a colon and the module name. For example: <code>-x
test:tapestry-ioc</code></li></ul></li><li>Eclipse Gradle IDE users:<ul><li>In
your External Tools Configuration, add the same -x test option as above at
Arguments > Program Arguments.</li></ul></li></ul><h3
id="BuildingTapestryfromSource-RunningtheIntegrationTestAppsManually">Running
the Integration Test Apps Manually</h3><p>The Tapestry source includes several
small web apps that are used by the automated Selenium integration tests. You
can also run these apps manually to
try out nearly every browser-visible aspect of Tapestry. Just invoke the
corresponding Gradle tasks. This is mainly useful when debugging failing
selenium tests.</p><ul><li>Command-line users:<ul><li>./gradlew
runTestApp1</li></ul></li><li>Eclipse users:<ul><li>Use the run-jetty-run
plugin in Eclipse, with the context directory selected from among the
<code>test</code> context directories. For example, in the tapestry-core
module, right click on the /src/test/app1 (or app2, etc) folder, and select Run
As > Run Jetty, then open your browser to <a class="external-link"
rel="nofollow"
href="http://localhost:8080/tapestry-core";>http://localhost:8080/tapestry-core</a></li></ul></li></ul><p>The
integration test apps are:</p><ul><li>activationctx – used
by tapestry-core integration tests</li><li>activationctx2 –
used by tapestry-core integration tests</li><li>app0 – used
only by the tapestry-hibernate integration tests</li><li><strong>app1 
211; used by most of the tapestry-core integration
tests</strong></li><li>app2 – used by tapestry-core integration
tests (HTTPS)app3 – used by tapestry-core integration
tests</li><li>app4 – used by tapestry-core integration
tests</li><li>app5 – used by tapestry-core integration
tests</li><li><em>appfolder</em>  – used by tapestry-core
integration tests</li><li>cluster – used by tapestry-core
integration tests</li><li>linktrans – used by tapestry-core
integration tests</li><li>symbolparam – used by tapestry-core
integration tests</li><li>(...and a few others not yet documented, and without
Gradle tasks yet. Search for web.xml files in the Tapestry
source.)</li></ul><h3 id="BuildingTapestryfromSource-MakingCodeChanges">Making
Code Changes</h3><p>Once you have cloned or pulled the latest changes to your
local Git repository, you can start working on it. Whenev
er you make some changes to the codebase, it's good to have a related issue
filed in JIRA and to use a similarly named branch in your local Git repository.
For example, to create a branch for an issue with the key TAP5-123:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre><code class="language-java">git branch TAP5-123 origin/master</code></pre>
</div></div><p>With per-issue branches you can easily switch back and forth
between different issues without worrying about unwanted side-effects from
unfinished changes to other issues. Whenever you want to work on the TAP5-123
example issue, simply checkout that branch and start making your
changes:</p><div class="code panel pdl" style="border-width: 1px;"><div
class="codeContent panelContent pdl">
<pre><code class="language-java">git checkout TAP5-123</code></pre>
@@ -150,7 +150,7 @@
<pre><code class="language-java">git commit</code></pre>
</div></div><h3
id="BuildingTapestryfromSource-Pushingyourcommitsupstream">Pushing your commits
upstream</h3><p>First:</p><ul><li>Run the full suite of tests before pushing
your commits to the upstream (remote) repository.</li><li>Ensure your changes
have full test coverage</li><li>Ensure you have set your local repo to track
the official Tapestry repo as its upstream
repository.</li></ul><p>Then:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre><code class="language-java">git push</code></pre>
-</div></div><h3 id="BuildingTapestryfromSource-ProducingPatches">Producing
Patches</h3><p>If you aren't an official committer (with write access to the
Apache Tapestry Git repo), you'll need to submit changes via a patch. See the
recommendations at <a class="external-link"
href="http://commons.apache.org/patches.html";>http://commons.apache.org/patches.html</a>.
(Obviously that isn't specifically for the Tapestry project, but most of the
same principles apply.)</p><p>You can use the git format-patch command to
produce a nice set of patches to attach to the relevant issue in JIRA:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+</div></div><h3 id="BuildingTapestryfromSource-ProducingPatches">Producing
Patches</h3><p>If you aren't an official committer (with write access to the
Apache Tapestry Git repo), you'll need to submit changes via a patch.See the
recommendations at <a class="external-link"
href="http://commons.apache.org/patches.html";>http://commons.apache.org/patches.html</a>.
(Obviously that isn't specifically for the Tapestry project, but most of the
same principles apply.)</p><p>You can use the git format-patch command to
produce a nice set of patches to attach to the relevant issue in JIRA:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
<pre><code class="language-java">git format-patch origin/master
</code></pre>
</div></div><p>The sooner you share your work the better. You can repeat the
steps of this workflow as often as you like, producing more patches to be
attached to the issue tracker. Once some of your patches are accepted and
applied by a committer, you can rebase your work against the latest trunk.
Alternatively, if you're asked to make some changes, you can go back to the
original Git commit and modify it until the project team accepts your
changes.</p><h3
id="BuildingTapestryfromSource-TroubleshootingHints">Troubleshooting
Hints</h3><p><strong>Problem 1:</strong> I can't run the build. it gives me an
error in line 91:</p><div class="code panel pdl" style="border-width:
1px;"><div class="codeContent panelContent pdl">
@@ -158,7 +158,7 @@
20:22:11.439 [ERROR] [org.gradle.BuildExceptionReporter] A problem occurred
evaluating root project 'tapestry-project-trunk'.
20:22:11.440 [ERROR] [org.gradle.BuildExceptionReporter] Cause: Cannot get
property 'plus' on null object
</code></pre>
-</div></div><p><strong>Solution:</strong> Use the gradle wrapper (./gradlew
build), not plain "gradle".</p><hr><p><strong>Problem 2</strong>: Under Linux I
get <a class="external-link" href="http://java.io";
rel="nofollow">java.io</a>.FileNotFoundException saying "Too many open
files"</p><p><strong>Solution</strong>: You may have to increase the number of
files your operating system allows you to have open at once. Try <code>ulimit
-n</code> to see what the current value is, and if it is less than 2048,
increase it to 2048 by editing your <code>/etc/security/limits.conf</code>
file. See your operating system's documentation for
details.</p><hr><p><strong></strong></p><p><strong>Problem 3:</strong> The
gradle build opens a Firefox browser with a File Not Found error:</p><div
class="code panel pdl" style="border-width: 1px;"><div class="codeContent
panelContent pdl">
+</div></div><p><strong>Solution:</strong> Use the gradle wrapper (./gradlew
build), not plain "gradle".</p><hr><p></p><p><strong>Problem 2</strong>: Under
Linux I get <a class="external-link" href="http://java.io";
rel="nofollow">java.io</a>.FileNotFoundException saying "Too many open
files"</p><p><strong>Solution</strong>: You may have to increase the number of
files your operating system allows you to have open at once. Try <code>ulimit
-n</code> to see what the current value is, and if it is less than 2048,
increase it to 2048 by editing your <code>/etc/security/limits.conf</code>
file. See your operating system's documentation for details.</p><hr><p><strong>
</strong></p><p><strong>Problem 3:</strong> The gradle build opens a Firefox
browser with a File Not Found error:</p><div class="code panel pdl"
style="border-width: 1px;"><div class="codeContent panelContent pdl">
<pre><code class="language-java">Firefox can't find the file at
chrome://src/content/RemoteRunner.html
?sessionId=74c5c263747249739d82e4bee33fb4b6&multiWindow=true&baseUrl=
http://localhost:9090/&debugMode=false&driverUrl=http://localhost:4444/selenium-server/driver/.</code></pre>
Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.
