Versions Compared

Old Version 89

changes.mady.by.user Marco Marasca

Saved on

compared with

New Version 90

changes.mady.by.user Jay Hodgson

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Table of Contents
minLevel3

...

UI Development

Set up the Maven Build

  1. Fork the Sage-Bionetworks SynapseWebClient repository into your own GitHub account: https://Create a GitHub user account if you don't already have one.
    1. Contributors should fork the repository and submit GitHub Pull Requests for code inclusion.

  2. Set up Git: https://help.github.com/articles/set-up-git

  3. Fork the Sage-Bionetworks SynapseWebClient repository into your own GitHub account: https://help.github.com/articles/fork-a-repo

  4. Clone the SynapseWebClient project down to your computer: git clone https://github.com/[YOUR GITHUB NAME]/SynapseWebClient.git
  5. Change into the proper directory with: cd SynapseWebClient
  6. Set up upstream with: git remote add upstream https://github.com/Sage-Bionetworks/SynapseWebClient
  7. Fetch and merge changes from the Sage Bionetworks repo, which was named upstream: 
    git fetch upstream

Setup with Intellij

  1. Download IntelliJ community edition, it comes pre-built with GWT and Maven support. 
  2. Install GWT SDK (install the actual SDK, not the eclipse plugin version)
    1. If downloading Java for the first time then download Java 8 as well.
  3. If you want to run Maven manually then install it from here (this will require you to add the mvn installation directory to your PATH as well), otherwise see notes here on configuring IntelliJ to run maven build.
  4. Configure settings.xml –- its a configuration file for running maven
  5. The file needs to placed in $HOME/.m2/settings.xml (e.g. michael/.m2/settings.xml)

    6. The template for the file needs to look like so-

    Code Block
    languagexml
    titlesettings.xml
    <settings xmlnsConfigure settings.xml –- its a configuration file for running maven
    1. The file needs to placed in $HOME/.m2/settings.xml (e.g. jane/.m2/settings.xml)

    2. This should be the content of this file:

      Code Block
      languagexml
      titlesettings.xml
      <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"           xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                      http://maven.apache.org/xsd/settingsxsd/settings-1.0.0.xsd">
  <localRepository/>
  <interactiveMode/>
  <usePluginRegistry/>
  <offline/>
  <pluginGroups/>
  <servers/>
  <mirrors/>
  <proxies/>
  <profiles>
    <profile>
      <id>dev-environment</id>
      <activation>
        <activeByDefault>true</activeByDefault>
      </activation>
      <properties>
		<org.sagebionetworks.portal.endpoint>http://127.0.0.1:8888/Portal.html</org.sagebionetworks.portal.endpoint>
         <!--<org.sagebionetworks.repositoryservice.endpoint>https://repo-prod.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint>
        <!-- insert properties described below here -->

  
   </properties>     </profile>
  </profiles>
  <activeProfiles/!-- <org.sagebionetworks.repositoryservice.endpoint>https://repo-staging.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint> -->
      </properties>
    </profile>
  </profiles>
  <activeProfiles/>
</settings>
  6. Import the SWC into IntelliJ by File → New Project From Existing Sources... <Select Path to SWC Location>
  7. If running Maven manually run like so (see note below on saving build time by running in debug mode):
    1. Run 'mvn clean install'
    2. Run 'mvn gwt:run'

Set up the Eclipse Build

...


...

Setup with Eclipse

  1. Install the latest Eclipse (for Java Development)
  2. Install the Google Plug-in for Eclipse.  Do not include GWT SDK in the install (GWT SDK will be installed by the maven install).  Do not install the Google App Engine Maven Integration.
  3. Install the Maven2Eclipse plugin: http://download.eclipse.org/technology/m2e/releases
  4. Create a GitHub user account
    1. Contributors should fork the repository and submit GitHub Pull Requests for code inclusion.

  5. Set up Git: https://help.github.com/articles/set-up-git

  6. Import the project as a maven project
    1. File → Import → Maven → Existing Maven Projects
    2. Next, in Root Directory enter the local path to your repository clone
    3. Next, Finish 
  7. You need to make sure the Import the project as a maven project
    1. File → Import → Maven → Existing Maven Projects
    2. Next, in Root Directory enter the local path to your repository clone
    3. Next, Finish 
  8. You need to make sure the GWT xml files are on the classpath. All of these resources can be found in src/main/resources and src/test/resources directories. 
    1. Right-click on portal (project name) → Build Path → Configure Build Path...
    2. Remove the "Exclude" filter from the source tab on the src/main/resources and src/test/resources directories.
  9. We need to tell the GWT Eclipse-plugin that this is a GWT project. Do this by Right-Clicking on the project in the package explorer and select: Google → Web Toolkit Settings...
    1. From the resulting dialog make sure the "Use Google Web Toolkit" check box is selected.
    2. Also make sure you are using the GWT SDK from your local maven repository (.m2/repository/com/google/gwt)
    We need to tell the Google plugin where our web app directory can be found.  Right-click
  10. Verify GWT can compile your code
    1. Right-Click on the project
    in
    1. from the package explorer
    and select Properties.
    1.  From the tree on the left of the dialog navigate to Google → Web Application
    2. Check the the check box: "This project has a WAR directory"
    3. With the "Browse" button, select "src/main/webapp"
    4. UN-CHECK the "Launch and deploy from this directory"  This is very important, if you keep this checked then Maven will not be able to generate a clean WAR file.  If you see "GWT needs to recompile" when you deploy your WAR then you probably have this box checked.
  11. Now make sure GWT can compile your code
    1. Right-Click on the project from the package explorer.
    2. Select Google→GWT Compile...
    3. Under the "Entry Point Modules" you should see "PortalDebug - org.sagebionetworks.web",  if not, then add it with the add button.
    4. Remove the "Portal - org.sagebionetworks.web" entry.
    5. The first time you run this you will be asked to select the output directory where GWT will compile the code. You want this to match the Maven WAR output directory, so use "target/portal-<VERSION>-SNAPSHOT"
    6. If you get compilation errors from the JavaScript validator (i.e. NullPointerException), navigate to the project's properties → JavaScript → Include Path → Source, and exclude all files from the source. If an OutOfMemoryError was thrown while compiling, you can click the "Advanced" tab towards the bottom of the Google → GWT Compile window and add "-Xms512M -Xmx1524M" to the VM arguments to increase heap space.
    12. SWC uses Sass , in order to automatically transpile to css in Eclipse (this is done automatically by maven) we need to add a custom builder:
  12. Install sass: https://sass-lang.com/install
  13. Open the project properties and navigate to Builders
  14. Create a new (Program) Builder, using the installed sass location as the Location value (e.g. /usr/local/bin/sass)
  15. Set the Working directory to the SWC project (e.g. ${workspace_loc:/portal})

    16. Set the following arguments (might vary according to the version):

    Code Block
    --unix-newlines
--sourcemap=none
--style compressed
--default-encoding=UTF-8
--stop-on-error
--no-cache
--update 
src/main/webapp/sass:target/portal-develop-SNAPSHOT
    For the latest version of sass (1.26.8 at the time of writing):
    Code Block
    --no-source-map
--style=compressed
--unicode
--stop-on-error
--update 
src/main/webapp/sass:target/portal-develop-SNAPSHOT
  16. Under Build Options - Allocate Console, Launch in background, and run this builder during all operations listed.
  17. If the GWT Compile successfully compiled, then you're ready to run the application.
    1. Option 1: start from within Eclipse.
      1. Right-Click on the project in the package explorer
      2. Select: Run As → GWT Development Mode with Jetty, and select Portal.html
      3. Set the run configuration VM Arguments to the following: "-Xms512m -Xmx2048m -XstartOnFirstThread".
      4. Double-click on the link provided in the Development Mode window to view the portal in your browser. 
    2. Option 2: build and run from the command line.
      1. Run 'mvn clean install'
      2. Run 'mvn gwt:run'

Eclipse Workspace Settings

Set file encoding to UTF-8 and the line-endings (for new files) to Unix, so that text files are saved in a format that is not specific to the Windows or Mac OS and most easily shared across heterogeneous developer desktops:

  • Open Preferences
  • Navigate to the Workspace preferences: General → Workspace
  • Change the Text File Encoding to UTF-8
  • Change the New Text File Line Delimiter to Other and select Unix from the drop-down

Troubleshooting

  • Check your exclusion filters through configure build path in Eclipse to assure nothing is excluded, then refresh and clean the SWC project.
  • "Could not deserialize" or similar problems in Super Dev Mode are most often fixed by re-building through the command line (running 'mvn clean install')
  • (git) Pull the latest changes from the upstream repository.
  • Try to rebuild your Eclipse's Portal project and keep your files in place.
  • Perform a Maven update.  
  1. Delete your project from Eclipse (leave "Delete project contents on disk" UNCHECKED)
  2. Go to the project root on your file system and delete .classpath, .project and the .settings/ folder
  3. Go to Step 6 in "UI Development above"
    1. .
    2. Select Google→GWT Compile...
    3. Under the "Entry Point Modules" you should see "PortalDebug - org.sagebionetworks.web",  if not, then add it with the add button.
    4. Remove the "Portal - org.sagebionetworks.web" entry.
    5. The first time you run this you will be asked to select the output directory where GWT will compile the code. You want this to match the Maven WAR output directory, so use "target/portal-<VERSION>-SNAPSHOT"
    6. If you get compilation errors from the JavaScript validator (i.e. NullPointerException), navigate to the project's properties → JavaScript → Include Path → Source, and exclude all files from the source. If an OutOfMemoryError was thrown while compiling, you can click the "Advanced" tab towards the bottom of the Google → GWT Compile window and add "-Xms512M -Xmx1524M" to the VM arguments to increase heap space.
  4. SWC uses Sass , in order to automatically transpile to css in Eclipse (this is done automatically by maven) we need to add a custom builder:
    1. Install sass: https://sass-lang.com/install
    2. Open the project properties and navigate to Builders
    3. Create a new (Program) Builder, using the installed sass location as the Location value (e.g. /usr/local/bin/sass)
    4. Set the Working directory to the SWC project (e.g. ${workspace_loc:/portal})

    5. Set the following arguments:

      Code Block
      --no-source-map
--style=compressed
--unicode
--stop-on-error
--update 
src/main/webapp/sass:target/portal-develop-SNAPSHOT


    6. Under Build Options - Allocate Console, Launch in background, and run this builder during all operations listed.
  5. If the GWT Compile successfully compiled, then you're ready to run the application.
    1. Right-Click on the project in the package explorer
    2. Select: Run As → GWT Development Mode with Jetty, and select Portal.html
    3. Double-click on the link provided in the Development Mode window to view the portal in your browser. 
  6. To run the unit tests:
    1. Right-Click on the project from the package explorer.
    2. Select: Run As → JUnit Test

Setup with Intellij

  1. Download IntelliJ community edition, it comes pre-built with GWT and Maven support. 
  2. Install GWT SDK (install the actual SDK, not the eclipse plugin version)
    1. If downloading Java for the first time then download Java 8 as well.
  3. If you want to run Maven manually then install it from here (this will require you to add the mvn installation directory to your PATH as well), otherwise see notes here on configuring IntelliJ to run maven build.
  4. Import the SWC into IntelliJ by File → New Project From Existing Sources... <Select Path to SWC Location>
  5. If running Maven manually run like so (see note below on saving build time by running in debug mode):
    1. Run 'mvn clean install'
    2. Run 'mvn gwt:run'

Eclipse Workspace Settings verification

Set file encoding to UTF-8 and the line-endings (for new files) to Unix, so that text files are saved in a format that is not specific to the Windows or Mac OS and most easily shared across heterogeneous developer desktops:

  • Open Preferences
  • Navigate to the Workspace preferences: General → Workspace
  • Change the Text File Encoding to UTF-8
  • Change the New Text File Line Delimiter to Other and select Unix from the drop-down

Troubleshooting

  • Check your exclusion filters through configure build path in Eclipse to assure nothing is excluded, then refresh and clean the SWC project.
  • (git) Pull the latest changes from the upstream repository.
  • Try to rebuild your Eclipse's Portal project and keep your files in place.
  • Perform a Maven update.  
  1. Delete your project from Eclipse (leave "Delete project contents on disk" UNCHECKED)
  2. Go to the project root on your file system and delete .classpath, .project and the .settings/ folder
  3. Go to "Set up with Eclipse" or "Set up with Intellij"

If using Eclipse, verify the web app directory is correct. Right-click on the project in the package explorer and select Properties:

  1.  From the tree on the left of the dialog navigate to Google → Web Application
  2. Check the the check box: "This project has a WAR directory"
  3. With the "Browse" button, select "src/main/webapp"
  4. UN-CHECK the "Launch and deploy from this directory"  This is very important, if you keep this checked then Maven will not be able to generate a clean WAR file.  If you see "GWT needs to recompile" when you deploy your WAR then you probably have this box checked

If this still doesn't work, or your dev mode is broken for another reason, there are some further steps you can take.
(Check out this site for more information: http://www.eclipsezone.com/eclipse/forums/t61566.html)

...

Set the repository endpoint parameters in your maven settings.xml file. 

To point to staging set:

<org.sagebionetworks.repositoryservice.endpoint>https://repo-staging.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint>

To point to production set:

...