Page History

...

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), or version 1.8 for Tapestry 5.5 and later.
• Install an IDE (IDEA IntelliJ is recommended (and free to Tapestry committers), but Eclipse will also work. NetBeans is reported to work as well.
• Install Firefox: For Tapestry 5.4.x and earlier, install Firefox browser version 3.642 or earlier, needed for the integration tests (because newer versions require a newer version of Selenium than Tapestry's Java version requirements allow).
• Set the Firefox browser's "preferred language" to English (en), because some tests will otherwise fail. (Fixed; see TAP5-2413)
• Install a Git client
  • Command-line users: http://git-scm.com/downloads
  • Eclipse users: Install install EGit from the Eclipse Marketplace, then in In Window > Preferences > Team > Git, set your "Default repository folder" (e.g. ~/git or %HOME%\git). Note that for Eclipse 4.4 (Luna) and later this is already doneGit support is built in.
• Install Gradle 1.0-milestone-3 or newer (or a Gradle plugin to your IDE),
  • Command-line users: http://www.gradle.org/downloadsnothing to do (Tapestry's Gradle wrapper, gradlew, will download Gradle automatically on first use).
  • 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.

Getting Started

Please read https://git-wip-usgitbox.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 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

  gitbox.apache.org/repos/asf/tapestry-5.git

   

  
  

• Eclipse EGit users:
  • Switch to Git perspective; then copy one of the URLs URL 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.)

...

• 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(for Mac/Linux) or gradlew.bat (for Windows) 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".

...

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

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.

...

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.

• Command-line users:
  • ./gradlew runTestApp1
• If using Eclipse users:
  • 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:

git branch TAP5-123 origin/master

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:

git checkout TAP5-123

It's a good idea to commit your changes to your local Git repo whenever you have finished one logical part of the issue. For example when refactoring, make a new commit for each refactoring step you take.

git commit

Pushing your commits upstream

First:

• Run the full suite of tests before pushing your commits to the upstream (remote) repository.
• Ensure your changes have full test coverage
• Ensure you have set your local repo to track the official Tapestry repo as its upstream repository.

Then:

git push

Producing Patches

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 http://commons.apache.org/patches.html. (Obviously that isn't specifically for the Tapestry project, but most of the same principles apply.)

You can use the git format-patch command to produce a nice set of patches to attach to the relevant issue in JIRA:

git format-patch origin/master

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.

Troubleshooting Hints

Problem: I can't run the build. it gives me an error in line 91:

20:22:11.438 [ERROR] [org.gradle.BuildExceptionReporter] * What went wrong:
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

The integration test apps are:

• activationctx – used by tapestry-core integration tests
• activationctx2 – used by tapestry-core integration tests
• app0 – used only by the tapestry-hibernate integration tests
• app1 – used by most of the tapestry-core integration tests
• app2 – used by tapestry-core integration tests (HTTPS)
• app3 – used by tapestry-core integration tests
• app4 – used by tapestry-core integration tests
• app5 – used by tapestry-core integration tests
• appfolder  – used by tapestry-core integration tests
• cluster – used by tapestry-core integration tests
• linktrans – used by tapestry-core integration tests
• symbolparam – used by tapestry-core integration tests
• (...and a few others not yet documented, and without Gradle tasks yet. Search for web.xml files in the Tapestry source.)

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:

git branch TAP5-123 origin/master

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:

git checkout TAP5-123

It's a good idea to commit your changes to your local Git repo whenever you have finished one logical part of the issue. For example when refactoring, make a new commit for each refactoring step you take.

git commit

Pushing your commits upstream

First:

• Run the full suite of tests before pushing your commits to the upstream (remote) repository.
• Ensure your changes have full test coverage
• Ensure you have set your local repo to track the official Tapestry repo as its upstream repository.

Then:

git push

Producing Patches

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 http://commons.apache.org/patches.html. (Obviously that isn't specifically for the Tapestry project, but most of the same principles apply.)

You can use the git format-patch command to produce a nice set of patches to attach to the relevant issue in JIRA:

git format-patch origin/master

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.

Troubleshooting Hints

Problem 1: I can't run the build. it gives me an error in line 91:

20:22:11.438 [ERROR] [org.gradle.BuildExceptionReporter] * What went wrong:
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

Solution: Use the gradle wrapper (./gradlew build), not plain "gradle".

...

Problem 2: Under Linux I get java.io.FileNotFoundException saying "Too many open files"

Solution: You may have to increase the number of files your operating system allows you to have open at once. Try ulimit -n to see what the current value is, and if it is less than 2048, increase it to 2048 by editing your /etc/security/limits.conf file. See your operating system's documentation for details.

...

Problem 3: The gradle build opens a Firefox browser with a File Not Found error:

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/.

You probably have a newer version of Firefox than is supported by the Selenium tests.

Solution: You must use Firefox version 42 or earlier. Be sure to configure it not to upgrade itself. This problem will go away when Tapestry discontinues support for Java 6, currently planned for Tapestry v5.5Solution: Use the gradle wrapper (./gradlew build), not plain "gradle".