Skip to end of banner
Go to start of banner

Developer Bootstrap

Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 105 Next »

UI Development

Set up the Maven Build

  1. 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 your local git environment according to Sage’s GitHub Security guidance

  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: 
    cd SynapseWebClient
  6. If you didn't set up the global pre-commit hook in step #2, set up a local pre-commit hook to detect secrets (do this for all repos that you clone in the future!):
    git secrets --install
    git secrets --register-aws
  7. Set up upstream with: 
    git remote add upstream https://github.com/Sage-Bionetworks/SynapseWebClient
  8. Fetch and merge changes from the Sage Bionetworks repo, which was named upstream: 
    git fetch upstream
  9. Configure 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:

      settings.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
                      http://maven.apache.org/xsd/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 -->
        <!-- <org.sagebionetworks.repositoryservice.endpoint>https://repo-staging.prod.sagebase.org/repo/v1</org.sagebionetworks.repositoryservice.endpoint> -->
      </properties>
    </profile>
  </profiles>
  <activeProfiles/>
</settings>

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. 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 
  4. 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.
  5. 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)
  6. Verify 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.
  7. SWC uses Sass. SCSS compilation is done by Maven during the compile step. To do this automatically in Eclipse (without compiling the entire app), we can add a custom builder
    1. Open the project properties and navigate to Builders
    2. Create a new Program Builder
      1. Set the Location value to the installed node binary: ${workspace_loc:/portal/node/node}
      2. Set the Working directory to the SWC project (e.g. ${workspace_loc:/portal})

      3. Set the following arguments:

        ${workspace_loc:/portal/node/yarn/dist/bin/yarn.js}
sass
--no-source-map
--style=compressed
--unicode
--stop-on-error
--update 
--load-path=node_modules
src/main/webapp/sass:target/portal-develop-SNAPSHOT/generated
    3. Under Build Options - Allocate Console, Launch in background, and run this builder during all operations listed.
  8. Since we're using Jetty in Eclipse, we also need to make sure our JavaScript dependencies that we pulled from NPM are copied to the src/main/webapp folder
    1. Open the project properties and navigate to Builders
    2. Create a new Ant Builder
      1. Set the Buildfile to ${workspace_loc:/portal/copy_eclipse_deps.xml}
      2. Set the Base Directory to ${workspace_loc:/portal}
      3. Go to the Targets tab. For "Auto Build", click "Set Targets" and select copy
  9. 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. 
  10. 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. To Setup running the GWT server from Intellij
    1. In the Menu bar Run > Edit configurations
    2. Click the "+" button to add an new configuration and choose "GWT Configuration".
    3. This is what the configuration looks like on Windows, adapt the file paths to your project repository's location
      1. Dev Mode Parameter should be:
        1. -war target/portal-develop-SNAPSHOT

    4. The "Before Launch" tools can be ignored.
      1. It is simply a shortcut a execute the same command executed by the libsass-maven-plugin in the root pom.xml if using Maven to run GWT.
      2. The alternative is to run this command manually in the command line, whenever the CSS gets messed up.
        sass --no-source-map --load-path=node_modules --style=compressed --unicode --stop-on-error --update "./src/main/webapp/sass":"./target/portal-develop-SNAPSHOT"
        • This is caused by the GWT runner in IntelliJ sometimes clearing out the /target directory when recompiling
        • Even setting up SASS command in the "before launch" does ensure the CSS is compiled automatically
          • The CSS will be compiled immediately before the GWT server runs. The GWT server then clears out the /target folder containing the compiled CSS
          • The only benefit to the set up is that a tab for SASS is created next to the GWT Server's tab, which you can then manually run after the GWT server has started up.
          • This is very annoying and any improvements to this workflow would be greatly appreciated.
  6. 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'
      1. Not recommended because it currently does not detect changes to the .ui.xml files, which forces you to kill, redo mvn clean install, and restart the server.
      2. Running in the IDE will detect .ui.xml changes


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)

  1. Use the '-clean' argument.
    1. One way to do this is to add -clean on its own line as the first line on the eclipse.ini file, and restart Eclipse.
  2. Use a new workspace.
    1. I followed the instructions in the site linked above. The gist of it is:
      1. Export your preferences to somewhere outside your Eclipse environment environment (Export → General → Preferences. Make sure that 'Export All' is checked.)
      2. Switch to a new workspace. (Switch Workspace → Other, then name your new workspace.)
      3. Import your preferences into this new workspace (Import → General → Preferences, make sure 'Import All' is checked.)
      4. Import trunk as usual.

Technologies used

There are several technologies that we are currently utilizing in the portal. The following is a list of primers for each:

Cross-browser testing

We have a shared account to use BrowserStack to test the website for cross browser compatibility issues.
Alternatively, for testing IE on Mac I use VirtualBox with an image provided by Microsoft from modern.IE.  For this to work, in your Windows VM, you will need to map an ip to outer in order to access your local machine (note, Windows UAC requires you to do this as an admin).

How to limit GWT build permutations

To speed up build time, add the following property to your local maven settings.xml file:

<gwt.module.suffix>Debug</gwt.module.suffix>

How to point to the local stack

  1. Follow the instructions on the Platform Bootstrap to set up local backend stack. 

  2. Build and launch a local backend stack.  From an up-to-date clone of Synapse-Repository-Services on your local box:

    1. Build the local stack by running 'mvn clean install -Dorg.sagebionetworks.database.drop.schema=true'.

    2. Now launch it:
      1. cd integration-test
      2. mvn cargo:run

    3. Verify the services are running correctly by visiting http://localhost:8080/services-repository-develop-SNAPSHOT/repo/v1/version you should see something like this:

      {"version":"develop-SNAPSHOT"}
  3. In the SWC project root pom.xml, change the synapse.version tag to develop-SNAPSHOT (so that the dependency is pointing to the code that's running on your local stack).
  4. Set the repository endpoints in your maven settings.xml file by adding the following properties:

Note that emails will not be sent when pointing to a local repo, the SynapseEmailService will instead write files to the devdata.sagebase.org s3 bucket in format <to_email_address>.json

Restart the Portal app to load these properties from settings.xml.

How to point to a remote stack

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

To point to the development stack set:

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

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:

Restart the Portal app to load this property from settings.xml.

Documenting complicated UI in the code

To get the big picture of widget relationships, sometimes it is helpful to have a picture.  We are testing the use of tools like http://asciiflow.com/ to help in these situations.

Compile Report

To generate a compile report, set enableClosureCompiler to false in the root pom.xml

A note on IDEs and building

We are currently (Feb 2021) in a situation where the folder served in a local build can be different depending on the IDE and toolchain the individual developer has configured.

The primary issue is that serving through the GWT plugin in Eclipse results in serving the contents of src/main/webapp, while serving the app through mvn gwt:run results in serving target/portal-develop-SNAPSHOT. Recent changes to the build include copying critical resources directly to target/portal-develop-SNAPSHOT. This is a problem because Eclipse users won't see these resources in their local build.

We would also like to improve the developer experience in IntelliJ IDEA.

I (Nick Grosenbacher) have attempted to fix this issue with specific build-tools to copy certain dependencies and add them to the .gitignore, but we need to identify a cleaner, less brittle solution.


  • No labels