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

• Download the Unlimited Intellij from here: Download IntelliJ IDEA

• Following the instruction the IntelliJ installation because that is created and verified in 2022. The following instruction was written and verified around 2018.

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

Open

Open

• 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