Setup development environment on Windows

Owned by Patrick Tang
Last updated: Jan 07, 2023
4 min read

Configure paths and environment variables

  • Set up or check that Java & Maven & Git & Tomcat bin directories are in the System PATH variables (like eg below)
    (in Windows, search for "Edit System Environment", click on Environment Variables" then use Edit or New)

  • Set up as New system environment:  JAVA_HOME &  M2_HOME & MAVEN_OPTS (as below)

  • Configure other options to suit your preferences

The following example has the version numbers which was successfully used by Patrick Tang on December 30, 2019:

JAVA_HOME = C:\Program Files\Java\jdk-1.8.0_231
M2_HOME = C:\Program Files\apache-maven-3.6.3
MAVEN_OPTS = -Xms512m -Xmx512m -Dmaven.artifact.threads=10
PATH = C:\Program Files\Apache Software Foundation\Tomcat 9.0.30\bin;C:\Program Files\apache-maven-3.6.3\bin;C:\Program Files\Java\jdk-1.8.0_231\bin;C:\Program Files)\Git\bin

Note: if you already have a command prompt open, or a git shell window and you intend to use them, you will need to close the window and reopen.

Clone your fork of the source code

For example:

  • Fork JSword into your Github account (from tyndale/jsword - unless already done above)

  • Clone JSword on your computer

cd c:\dev
git clone GitHub - STEPBible/jsword: JSword (Note: If the command does not work try "git clone git@github.com:tyndale/jsword.git" on April 14, 2018)

We are not using the master branch for JSword. So you will need to switch branch once it is cloned:

cd jsword
git checkout jsword-stepbible-2022

(or use the Git ReadOnly URL options if you have not created yourself a github account
  Or download GitHub for Windows and "Clone")

  • Fork STEP from GitHub (from tyndale/step - unless already done above)

  • Clone STEP

cd c:\dev
git clone GitHub - STEPBible/step: STEP :: Scripture Tools for Every Person  
(Note: If the command does not work try "git clone git@github.com:tyndale/step.git" on April 14, 2018)

(or use the Git ReadOnly options if you have not created yourself a github account)

Build the code

Run the following commands from a git command prompt:

  • from the JSword source code directory. Make sure to build this first.

cd c:\dev\jsword
mvn clean install -DskipTests=true

  • from the Step source code directory

cd c:\dev\step
mvn clean install -DskipTests=true

In the future, you can just run mvn clean install on the base directory.

If you have issues with the build, you may need to update the <java.version> in the pom.xml file to 1.8 or the version that matches what you have installed.

Installing Intellij Community Edition

Old instruction for IntelliJ

  • Import the JSword as a Maven project 

    • File>New>Project from Existing sources:

    • "Import Project" then find the step folder (eg c:\dev\jsword)

    • "Import project..." "Maven"

    • Select (check) the "Import Maven projects automatically" option

 

  • accept defaults for Import Project

    • for SDK, click on "+" then select JDK and find the Java/jdk folder (23-Apr-2018 - it refused JDK 10 so used JDK 9)

  • Import the STEP software as a Maven project

    • File>New>Project from Existing sources:

    • "Import Project" then find the step folder (eg c:\dev\step)

    • "Import project..." "Maven"

    • Select (check) the "Import Maven projects automatically" option

    • for SDK, click on "+" then select JDK and find the Java/jdk folder

    • accept defaults for Import Project

  • Import STEP into JSword in a single project

    • File > Open > Project > pick c:\dev\jsword

    • File > Project structure > Modules > "+" > Import  module > pick c:\dev\step

  • Install Tomcat as a J2E container into Intellij

    • File > Settings > (Build, Execution, Deployment>) Application Servers >  + > Tomcat server 
      (click on "more items" if you don't see Tomcat listed)

    • find the folder (eg C:\dev\apache-tomcat-8.0.12)

  • Create a Run/Debug configuration 

    • menu Run > Run… > Edit configurations > "+" (top left on the screen) > Tomcat Server >Local

    • setup with: Name= Step (with data load)

    • Launch address: http://localhost:8080/?debug

    • Application server= (click on Configure and find Tomcat, eg C:\dev\apache-tomcat-8.0.12)

    • VM options=  -Dstep.loader=true -Dstep.development=true -Dstep.skipBookInstallation=true -Dstep.home=c:\dev\step.home -XX:+CMSClassUnloadingEnabled -XX:MaxPermSize=256M               
      (change the 'step.home' definition if the offlineModules are placed somewhere else)

      • Note: Patrick heard that 'step.home' is only needed for standalone installation with modules local on the hard drive.  

      • Note: -XX: +CMSPermGenSweepingEnabled is removed from the VM option because Java 9 would complain about that option and would not run.  

      • Note: Since step uses pipes (|) in the url you should add support for this to tomcat by adding tomcat.util.http.parser.HttpParser.requestTargetAllow=| to the catalina.properties file. Or if you are unable to edit the file, you can add another VM Option in the IntelliJ run config: -Dtomcat.util.http.parser.HttpParser.requestTargetAllow=|

    • In the TAB "Deployment" > + (top right) > Artifact > step-web:war exploded.  Make sure the "Application context:" is /

    • In the TAB "Server", under "Before launch: Build, Activate tool window" make sure "Build" is there.  If not add that.

    • TAB Server: On Update action= Redeploy;   On frame de-activation= Update classes and resources

  • Test the setup: 

    • menu Run 'Step (with data load)''
      (this should eventually start up the browser and run STEP)

  • Create a Run/Debug configuration without loading 
               (this will restart Step without creating/refreshing all your search indexes).

    • menu Run > Run… > Edit configurations >  

    • select "Step (with data load)" in the left column and click on the Copy symbol above it

    • Changes: Name= Step (without load); VM options=  -Dstep.development=true -Dstep.skipBookInstallation=true -XX:+CMSClassUnloadingEnabled -XX:+CMSPermGenSweepingEnabled -XX:MaxPermSize=256M

      Get started using Intellij   

      • To update the project:  menu VCS > Update project > select "Merge" and "Stash"

      • To find a file:  use Ctrl-Shift-N to look for file names, and Ctrl-Shift-F to look for file contents

      • To see the difference you've made before Commit: menu VCS > Show changes

      • To commit & push changes: menu VCS > Commit changes > add Message; change "commit" to "Commit and Push"; type Git ID & PW
        (this should commit into the your Fork of the project that you created at GitHub - see the intro at About pull requests - GitHub Docs ) 

      • at your GitHub page (eg https://github.com/<USERNAME>/step ) click on Pull Request then Create Pull Request and describe your changes