This is a guide to building Tapestry itself from source code. This is primarily of interest to Tapestry contributors, rather than Tapestry users.

Although Tapestry users 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.

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.

Prerequisites

Install a Java JDK (Sun/Oracle, not OpenJDK), version 1.7 (just to prevent VU#225657, see: http://www.kb.cert.org/vuls/id/225657).
Install an IDE (IDEA IntelliJ is recommended (and free to Tapestry committers), but Eclipse will also work. NetBeans is repor ted to work as well.
Install Firefox browser version 3.6, needed for the integration tests.
Set the Firefox browser's "preferred language" to English (en), because some tests will otherwise fail.
Install a Git client
- Command-line users: http://git-scm.com/downloads
- Eclipse users: Install EGit from the Eclipse Marketplace, then in In Window > Preferences > Team > Git, set your "Default repository folder" (e.g. ~/git or %HOME%\git)
Install Gradle 1.0-milestone-3 or newer (or a Gradle plugin to your IDE),
- Command-line users: http://www.gradle.org/downloads
- Eclipse users: Install Gradle IDE from the Eclipse Marketplace

Getting Started

Please read https://git-wip-us.apache.org/ first.

Windows users (especialy EGit users) should probably set the core.autocrlf config setting to false so that local diffs won't highlight line ending differences.

Clone the Repository

Clone Tapestry from the Git repo:

Command-line git users:
Non Committers:
git clone
http://git-wip-us.apache.org/repos/asf/tapestry-5.git

Committers:
git clone
https://git-wip-us.apache.org/repos/asf/tapestry-5.git
Eclipse EGit users:
- Switch to Git perspective; then copy one of the URLs above into paste buffer
- Right-click > Paste repository path or URI. This will bring up the Clone Git Repository dialog.
- Committers: make sure Protocol is https, and enter your Apache commiter LDAP user name & password
- click Next.
- Select the branches you're interested in (e.g 5.3 and master), click Next
- Select Directory to where you want the project source code (e.g. ~/git/tapestry-5 or %HOME%\git\tapestry-5)
- Select whichever "Initial Branch" you're interested in (e.g. master)
- Set "Remote name" to "origin" (the default)
- VERY IMPORTANT: uncheck the "Import all existing projects" checkbox (we'll do this using Gradle, below)
- Click Finish. (Be patient; the clone operation might take a few minutes.)

Gradle Preparation

Command-line gradle users only:
- If you're using Eclipse but not Gradle IDE do ./gradlew eclipse
- 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.
Eclipse Gradle IDE users:
- Switch to Java (or JEE) perspective and right-click > Import... > Gradle > Gradle Project > Next.
- Set the "Root folder" to where you put your Tapestry source in the previ ous section (e.g. ~/git/tapestry-5 or %Home%\git\tapestry-5)
- Click Build Model. Select the top-level (the top-level module and all sub-modules) then click Finish.
- Be sure the "Enable dependency management" and ""Add to workingset 'tapestry-5'" checkboxes are checked.
- Click Finish. (Be patient; the import operation might take a few minutes.)
Eclipse EGit users: Do a Git "Share" on the project:
- 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 Finish.

Antlr

The tapestry-core 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:

Eclipse Gradle IDE users:
- Right click on the build.gradle file within tapestry-core and click Run As > "Gradle build...", check only the generateGrammarSource task, and change the "Name" field to something like "tapestry-core antlr", then click Apply and Run.
- 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 tapestry-core project > Properties > Java Build Path > Source > Add Folder > find tapestry-core/build/generated-sources/antlr and check the checkbox next to it, then click OK.

CoffeeScript

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 co mpile time from their Coffeescript sources. In order to generate the JavaScript files you need to have Coffeescript installed and in your path. Simply install Node.js and afterwards run npm install -g coffee-script. The installation should take care of everything.

Eclipse Gradle IDE users:
- Right click on the build.gradle file within tapestry-core and click Run As > "Gradle build...", check only 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.
- 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 abou t that path. To fix that, right click on the tapestry-core project > Properties > Java Build Path > Source > Add Folder > find tapestry-core/build/generated-sources/compiled-coffeescript and tapestry-core/build/generated-sources/compiled-test-coffeescript and check the checkbox next to it, then click OK.

Generate CoffeeScript and Antlr files automatically when changed

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 tapestry-core project:

Eclipse Gradle IDE users:
- Right click on the tapestry-core project and select properties.
- Select the "Builders" entry from the list on the left and click "New.." in the right panel.
- Select "Program" and click "Ok".
- Give the program a meaningful name, e.g. "compile coffeescript and antlr".
- Switch to the "Main" tab.
- For "Location:" click "Browse Workspace..." and select gradlew.sh or gradlew.bat 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}".
- For "Working Directory:" click "Browse Workspace..." and select the Tapestry root project.
- For "Arguments:" enter tapestry-core:generateGrammarSource tapestry-core:compileCoffeeScript tapestry-core:compileTestCoffeeScript.
- Switch to the "Build Options" tab.
- Make sure that only "Allocate Console", "After a "Clean"", "During manual builds", "During auto builds" and "Specify working set of relevant resources" are checked.
- Click "Specify Resources...".
- From the "tapestry-core" p roject select "src/main/antlr", "src/main/coffeescript", and "src/test/coffeescript".
- Click "Finish".
- Click "OK".
- Click "OK".

Building

You can build individual modules, or (from the root folder) build everything.

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.
- ./gradlew build
Eclipse Gradle IDE users:
- Right click on the top-level project (or any sub-project) and select Run As > Gradle Build...

Running Tests

Eclipse users:

Install the TestNG plugin to allow running of individual TestNG unit tests from within in Eclipse.

The Tapestr y integration tests will repeatedly start up a Firefox browser.

Ensure that your environment will allow a connection to https://localhost:443

Skipping Tests

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.

Command-line users:
- ./gradlew build -x test
- You can skip tests on a specific module by adding a colon and the module name. For example: -x test:tapestry-ioc
Eclipse Gradle IDE users:

Running the Integration Test Apps Manually

The Tapestry source includes several web apps that are used by the automated Selenium inte gration tests. You can also run these apps manually to try out nearly every browser-visible aspect of Tapestry. (See a live example running on Google App Engine.)

If using Eclipse:
- Use the run-jetty-run plugin in Eclipse, with the context directory selected from among the test 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 http://localhost:8080/tapestry-core

Making Code Changes

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 JI RA 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:

This is a guide to building Tapestry itself from source code. This is primarily of interest to Tapestry contributors, rather than Tapestry users.

Although Tapestry users 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.

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.

Prerequisites

Install a Java JDK (Sun/Oracle, not OpenJDK), version 1.7 (just to prevent VU#225657, see: http://www.kb.cert.org/vuls/id/225657).
Install an IDE (IDEA IntelliJ is recommended (and free to Tapestry committers), but Eclipse will also work. NetBeans is repor ted to work as well.
Install Firefox browser version 3.6, needed for the integration tests.
Set the Firefox browser's "preferred language" to English (en), because some tests will otherwise fail.
Install a Git client
- Command-line users: http://git-scm.com/downloads
- Eclipse users: Install EGit from the Eclipse Marketplace, then in In Window > Preferences > Team > Git, set your "Default repository folder" (e.g. ~/git or %HOME%\git)
Install Gradle 1.0-milestone-3 or newer (or a Gradle plugin to your IDE),
- Command-line users: http://www.gradle.org/downloads
- Eclipse users: Install Gradle IDE from the Eclipse Marketplace

Getting Started

Please read https://git-wip-us.apache.org/ first.

Windows users (especialy EGit users) should probably set the core.autocrlf config setting to false so that local diffs won't highlight line ending differences.

Clone the Repository

Clone Tapestry from the Git repo:

Command-line git users:
Non Committers:
git clone
http://git-wip-us.apache.org/repos/asf/tapestry-5.git

Committers:
git clone
https://git-wip-us.apache.org/repos/asf/tapestry-5.git
Eclipse EGit users:
- Switch to Git perspective; then copy one of the URLs above into paste buffer
- Right-click > Paste repository path or URI. This will bring up the Clone Git Repository dialog.
- Committers: make sure Protocol is https, and enter your Apache commiter LDAP user name & password
- click Next.
- Select the branches you're interested in (e.g 5.3 and master), click Next
- Select Directory to where you want the project source code (e.g. ~/git/tapestry-5 or %HOME%\git\tapestry-5)
- Select whichever "Initial Branch" you're interested in (e.g. master)
- Set "Remote name" to "origin" (the default)
- VERY IMPORTANT: uncheck the "Import all existing projects" checkbox (we'll do this using Gradle, below)
- Click Finish. (Be patient; the clone operation might take a few minutes.)

Gradle Preparation

Command-line gradle users only:
- If you're using Eclipse but not Gradle IDE do ./gradlew eclipse
- 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.
Eclipse Gradle IDE users:
- Switch to Java (or JEE) perspective and right-click > Import... > Gradle > Gradle Project > Next.
- Set the "Root folder" to where you put your Tapestry source in the previ ous section (e.g. ~/git/tapestry-5 or %Home%\git\tapestry-5)
- Click Build Model. When it completes, select the top-level (the top-level module and all sub-modules).
- Be sure the "Enable dependency management" and "Create workingset 'tapestry-5' checkboxes are checked.
- Click Finish. (Be patient; the import operation might take a few minutes.)
Eclipse EGit users: Do a Git "Share" on the project:
- 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 Finish.

Antlr

The tapestry-core 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:

Eclipse Gradl e IDE users:
- Right click on the build.gradle file within tapestry-core and click Run As > "Gradle build...", check only the generateGrammarSource task, and change the "Name" field to something like "tapestry-core antlr", then click Apply and Run.
- 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 tapestry-core project > Properties > Java Build Path > Source > Add Folder > find tapestry-core/build/generated-sources/antlr and check the checkbox next to it, then click OK.

CoffeeScript

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 fro m their Coffeescript sources. In order to generate the JavaScript files you need to have Coffeescript installed and in your path. Simply install Node.js and afterwards run npm install -g coffee-script. The installation should take care of everything.

Eclipse Gradle IDE users:
- Right click on the build.gradle file within tapestry-core and click Run As > "Gradle build...", check only 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.
- 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. T o fix that, right click on the tapestry-core project > Properties > Java Build Path > Source > Add Folder > find tapestry-core/build/generated-sources/compiled-coffeescript and tapestry-core/build/generated-sources/compiled-test-coffeescript and check the checkbox next to it, then click OK.

Generate CoffeeScript and Antlr files automatically when changed

Eclipse Gradle IDE users:
- Right click on the tapestry-core project and select properties.
- Select the "Builders" entry from the list on the left and click "New.." in the right panel.
- Select "Program" and click "Ok".
- Give the program a meaningful name, e.g. "compile coffeescript and antlr".
- Switch to the "Main" tab.
- For "Location:" click "Browse Workspace..." and select gradlew.sh or gradlew.bat 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}".
- For "Working Directory:" click "Browse Workspace..." and select the Tapestry root project.
- For "Arguments:" enter tapestry-core:generateGrammarSource tapestry-core:compileCoffeeScript tapestry-core:compileTestCoffeeScript.
- Switch to the "Build Options" tab.
- Make sure that only "Allocate Console", "After a "Clean"", "During manual builds", "During auto builds" and "Specify working set of relevant resources" are checked.
- Click "Specify Resources...".
- From the "tapestry-core" project select "src/main/antlr", "src/main/coffeescript", and "src/test/coffeescript".
- Click "Finish".
- Click "OK".
- Click "OK".

Building

You can build individual modules, or (from the root folder) build everything.

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.
- ./gradlew build
Eclipse Gradle IDE users:
- Right click on the top-level project (or any sub-project) and select Run As > Gradle Build...

Running Tests

Eclipse users:

Install the TestNG plugin to allow running of individual TestNG unit tests from within in Eclipse.

The Tapestry integration tests will repeatedly start up a Firefox browser.

Ensure that your environment will allow a connection to https://localhost:443

Skipping Tests

Command-line users:
- ./gradlew build -x test
- You can skip tests on a specific module by adding a colon and the module name. For example: -x test:tapestry-ioc
Eclipse Gradle IDE users:

Running the Integration Test Apps Manually

The Tapestry source includes several 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.

If using Eclipse:
- Use the run-jetty-run plugin in Eclipse, with the context directory selected from among the test 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 http://localhost:8080/tapestry-core

Making Code Changes

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:

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:

 

Modified: websites/production/tapestry/content/cache/main.pageCache
==============================================================================
Binary files - no diff available.