This guide is Jerry's preferred software setup guide., It is what I use whenever I set up a new computer. I make updates each time I set things up again. If you are using it and anything is out of date, let me know and I'll work with you to update it. The intent is to document in a detailed manner every single step required. This should allow new folks to be up and running from a fresh computer in about 2 hours. This guide assumes you have a new 64 bit computer with Windows installed, but nothing else.
Step 0: Get Set Up on Accounts
Make sure you have accounts on Confluence, Stash, Jira, Slack, and an email account that you will use for any software related emails. Get set up on all of those before going forward.
Step 1: Start from a Fresh 64 bit Windows Computer
If you already have things installed on your computer, first uninstall Eclipse, Java JDK, any Git or Gradle you might have installed. This guide might work if you have those things installed but probably better chance and better setup if you uninstall old versions first.
Step 2: Use Windows 10 or 11 Operating System
This guide assumes you use the Windows 10 or 11 operating system. There are a few things that are specific to Windows in the setup. If you are using a different operating system, then one of the other setup guides will be a better place to start.
Step 3: Install Java JDK.
- As of May, 2021 use the following link to insatll Java: https://www.azul.com/downloads/?version=java-17-lts&package=jdk and select the disk image as a guideline to download Java JDK version 17.
- Run that executable. Allow it to make changes to your computer. Accept all the defaults (Click Next or OK on each choice). It will likely install it in C:\Program Files\Zulu\zulu-8\
Step 4: Install Eclipse
Eclipse is an IDE (Integrated Development Environment). It is where you write and launch Java code. It has some nice plugins that allow you to do just about everything you need from Eclipse itself and rarely need to do anything from outside of Eclipse. This guide tries to do everything it can from inside Eclipse when possible.
- Go to the Eclipse Download page at https://www.eclipse.org/downloads/
- Find the Download 64 bit button for the most recent version. As of April 2022 it was Eclipse IDE 2022-03. They have been doing a new version each month now. Whatever the most recent is will likely work for the following instructions. If not, let Jerry know and he'll get the most recent version and/or update the instructions.
- Click on the Download 64 bit button.
- Click on the Download Button. Give a donation if you are feeling good about life.
- eclipse-inst-win64.exe should download to your computer and show up in the bottom of your browser, or the downloads directory for your browser.
- Run eclipse-inst-win64.exe. It will start the Eclipse installer, with lots of possible options. Choose the first one (Eclipse IDE for Java Developers)
- Set the Installation Folder to C:\eclipse\java-2022-03 (change the 2022-03 to the version you are installing). Note: You may have to create that directory using the File Explorer first if it is telling you it cannot write to that folder. Select to create a start menu entry and a desktop shortcut. Click on Install.
- Accept all of the license agreements. Click on remember accepted licenses whenever the choice shows. Trust any certificates it asks you about.
- Click on Launch when it is done. It will ask you for a workspace location. Type in C:\Workspaces\EclipseWorkspace and Click "Use this as the default and do not ask again". Click Launch.
- A Welcome Screen will come up. This has a lot of tutorials and such. You might want to explore things later. But for now, X out of it, or click the Workbench arrow to get into eclipse.
- Exit Eclipse for now. We'll get back to it in a bit...
- Find the Eclipse launching icon, right click on it, and pin it to the taskbar on the bottom of your screen so you can quickly launch it later.
Step 5: Make Changes for Long Paths in Windows
(Not sure if this is needed any more with Windows 11. In Nov. 2021, I set up a computer and skipped this step and it seems to work for now at least... - Jerry)
- Follow the instructions #1 and #2 at Long Paths in Windows.
- Can skip #3 (Set Git’s core.longpaths = true) Seems like this is no longer necessary if you follow the instructions above.
- Reboot to make sure all changes have taken place.
Step 6: Fix Some Eclipse Settings
Some of these settings are required to do anything. Some will make your life easier.
- Exit Eclipse if it is running.
- Edit the -Xms and -Xmx lines in your [eclipse installation directory]/eclipse.ini file (C:/eclipse/java-2022-03/eclipse/eclipse.ini if installed as described above). Change them to read -Xms1024m and -Xmx4096m . (You might need to adjust these depending on RAM capacity, 1g and 4g are good for computers with 16GB of RAM). This will give Eclipse more memory to work with.
- Start Eclipse. Go to Window→Preferences Select the General→Workspace tab. Set the text file encoding to UTF-8 and the New text file line delimiter to Other: Unix.
- In Preferences, under Java→Installed JREs, make sure to select the Java17 JRE you installed (Add → select standard VM and click Next → click Directory and select folder C:\Program Files\Zulu\zulu-17 → finish) and remove any others:
- In Gradle Preferences, make sure to select 7.2 (or perhaps higher - check with Jerry if not sure) and point to the installed Java JRE:
- In Preferences, under Java→Compiler, make sure to set Compiler Compliance Level to 1.8
- In Preferences, under Java-> Compiler, Errors/Warnings, expand Deprecated and restricted API. Change "Forbidden reference (access rules)" from "Error" to "Ignore". Click Apply. Accept doing a full build if it asks you. Then click Apply and Close.
- Open Preferences again and under General→Keys, click on Binding to sort on order of binding. Find F11, which by default is set to Debug. Change that one to CTRL-F11 by clicking in the binding box and hitting those keys. This will show that there is a conflict with Run. Select Run and change it from CTRL-F11 to F11. This will make it easy to run things repeatedly by just hitting F11. Select Apply and Close.
- Open Preferences again and select Run/Debug→Launching. Select Always on Save required dirty editors before launching; Select Always launch the previously launched application. Should look like this. Select Apply and Close.
- Open Preferences and select Version Control (Team)→Git. Change connection timeout (seconds) to something like 300 instead of 30. Change Default repository folder to C:\repos. Click Apply and Close.
Step 7: Clone IHMC Code Repositories
In this guide, we will do everything under a repository-group. This will make it easy to get all the projects set up nicely. The code that will be cloned will be enough to run most things. However, if you start to develop on a lot of projects at that point you will need to become more of an expert in git, repositories, etc. For now, do the following.
- Run Eclipse. Open the Git Perspective. You can do this either by going to Window->Perspective→Open Perspective→Other... and Choosing Git, or clicking on the Open Perspective Button in the top right corner and choosing Git.
- Make the directory on your computer C:\repos\ Note: If you have a big and fast extra drive at D: or somewhere else, you can also put it there.
- In a Web Browser log into your account at stash.ihmc.us
- Click on Repositories→View All Public Repositories
- Find and Click on Repository Group. It should take you here: https://bitbucket.ihmc.us/projects/LIBS/repos/repository-group/browse
- Click the Clone Button.
- In the box that pops up, highlight the URL and do CTRL-C to copy it
- Go back to Eclipse. Make sure you are still in the Git Perspective. Click on the Clone Git Repository Button
- Fill in your stash username and password. Click on the store in secure store button Hit Next. Do the defaults of choosing all branches when the branch selection window shows up. Hit Next.
- Set the local directory to C:\repos\repository-group. Hit Finish. repository-group should load on your computer. There is no actual code in repository-group. It sets up the framework for installing code underneath it that will then be treated as one code base in Eclipse.
- Go back to your browser and back to the stash.ihmc.us page. Click on Repositories→View All Public Repositories again and this time find IHMC Open Source Libraries / IHMC Open Robotics Software. It will send you to https://stash.ihmc.us/projects/LIBS/repos/ihmc-open-robotics-software/browse
- Click on the clone button as above and CTRL-C the URL https://bitbucket.ihmc.us/scm/libs/ihmc-open-robotics-software.git
- Go back to Eclipse. Make sure you are still in the Git Perspective. Click on the Clone Git Repository Button. The info should be automatically entered. Your stash user name and password should still be filled in. Click Next twice.
- Change the location to C:\repos\repository-group\ihmc-open-robotics-software. (***Important: Make sure to not forget to put it under repository-group. Do not just put it at C:\repos***). Click Finish. The software will be pulled. There is quite a bit, so be patient. It'll take about ten minutes to load it all.
Step 8: Import Gradle Project
Anytime you clone a repo or import new code, you need to import gradle project so that Eclipse knows about your code and sets up everything nicely. A ton of things go on behind the scenes and several people spent a lot of time making the magic happen. If you are ever in the grateful feeling mood, find out who currently maintains gradle or bamboo or Bitbucket or any other software infrastructure, search them out and buy them lunch.
- Run Eclipse. In Eclipse, go to File→Import → Gradle → Existing Gradle Project. Click Next. Click Next if the Gradle Welcome Page shows up.
- Browse to the Project Root Directory C:\repos\repository-group. Click Next.
- Make sure that Override workspace settings is NOT checked, so that you use workspace settings. Click on Configure Workspace Settings and Select use specific gradle version and choose 7.2 as of November 2021. Select Apply and Close.
- Import options should now look like this: (Select Override workspace settings if gradle version is not updated in "Specific Gradle Version" and change it to 7.2)
- Click Next. This will process the various Gradle files, jar files, and figure out the directory structure. This step takes a few minutes. Be patient and count your blessings that you don't have to understand what is going on right now. Lots of magic is going on behind the scenes finding all the dependencies on the web.
- If you get an error there should be an error message. Slack it to Jerry or help-desk and find someone to help you. It can be tricky to decipher any error at this point. If there is not an error, you should get something that looks like this:
- Click Finish. This will import the Gradle projects. This step takes a few minutes. Be patient and count your blessings that you don't have to understand what is going on right now.
- Wait until all of the Eclipse messages in the lower right of the Eclipse screen are done. It will do some synchronizing, etc. Be patient. If there are any errors, find Jerry to help fix them.
- Compile the Code. (Project→Build All or CTRL-B). Give it a few minutes to finish compiling. Note: You can have Project→Automatically Build selected too. But sometimes when there are troubles, this can have issues. So first go maybe keep that off until things are all working well, then turn auto build back on.)
- Make sure there are no compile errors. Check the Problems View Tab. Errors will be in red. There will be a lot of warnings. But if any errors, find Jerry to help fix them.
- If you face the following errors go to Windows→Preference→Java→Installed JREs and change the location to what it says to use above. If still doesn't work, find Jerry or slack help-desk.
Step 9: Run SpringFlamingoSimulation and AtlasFlatGroundWalkingTrack
- If Eclipse is not running, start it up.
- Make sure you are in the Java Perspective Window of Eclipse. (Window->Perspective→Open Perspective→Other... Java(default) and Open. Or click the J Java button on the top right of the screen.)
- Open SpringFlamingoSimulation.java. Easiest is CTRL-Shift-T and search for it and open it. Or you can do Navigate→Type and search for it.
- Right Click. Select Run As→ Java Application. It may take a minute or two for the code base to compile if it isn't already compiled.
*Note: Go to Run → Run Configurations ... . In tab "Classpath" check "Use temporary JAR to specify classpath ...", if it is not checked. This will avoid long path issues.
- Push the Simulate button to have it simulate. Hit stop. Then play. Play around with the interface. X it out when done.
To change view in the viewport. Left click to and move the mouse to rotate the model and right click to rotate the camera. Press the mouse wheel and move the mouse up or down to zoom in or out.
- Play around with plotting variables. Click and drag them from the variable list to a graph window to plot a variable. Double click on the graph to change plotting parameters for the graph.
- Open AtlasFlatGroundWalkingTrack.java. Run it as a Java application. Select a robot config when prompted. Search for the YoVariable walkCSG and set it to true (1.0). Hit the simulate button and watch it walk.
- If you cannot run SpringFlamingo or AtlasFlatGroundWalkingTrack, find Jerry for help.
Step 10: Import Java Code Style Format
- Run Eclipse if it isn't running.
- Open the Preferences Window (Window→Preferences)
- Go to Java→Code Style→Formatter
- Click Import Button
- Import C:\repos\repository-group\ihmc-open-robotics-software\ihmc-java-toolkit\CodeFormatTemplates\IHMCEclipseFormatter.xml
- Click Open. Then Click Apply and Close.
Step 11: Pulling New Software
As people update software, you need to pull the new software. You should do this often. When programming new stuff, you should do it several times a day. If just using other stuff you should do it each day you use it. You want to stay up to date with the develop branch. The following instructions show how to stay up to date on develop. Later will show you how to do your own branch and keep it up to date with other code and check new things in.
- In Eclipse, open the Git perspective (Button in the top right corner).
- Under the Git Repositories tab is listed all your open repositories.
- One at a time, right click on a repository and select Pull...
- The first time you do this for each repository, drop down When pulling: Rebase, click the "Configure upstream for push and pull" check box, and hit Finish.
- A window will pop up showing the results. If there are any errors mentioned, find Jerry to help fix them and update this guide.
- Repeat for all of the listed repositories.
- Go to the Java Perspective in Eclipse (Button in top right corner).
- Find the Package Explorer Tab. If you can't find it, it might not be open. Do Window→Show View→Package Explorer.
- In the Package Explorer Tab, right click on one of the projects (doesn't matter which one) and select Gradle→Refresh Gradle Project.
- Give it a few minutes. While waiting count your blessings that you don't need to know all the magic happening behind the scenes. Progress will be shown in the bottom right. If you want to see more details, open the Progress View Tab.
- Recompile the Code. (Project→Build All or CTRL-B). Give it a few minutes to finish compiling. Progress Tab will show when it is done.
- Make sure there are no compile errors. Check the Problems View Tab. Errors will be in red. There will be a lot of warnings. But if any errors, find Jerry to help fix them.
- Run what you have been running to make sure it still works as expected. If not, someone's commit may have broken your code. There are ways to revert to old versions that will be described below. For now find someone knowledgeable to help you if you think someone broke things.
Step 12: Fixing global git ignore files
Git in eclipse can have trouble with ignoring obj graphics files, since it thinks they are obj compiled c files. Therefore:
- Search for any files named gitignore_global.txt on your drive. One example place to look is C:\Users\JerryPratt\Documents
- If you find any, see if they contain *.obj
- If so, delete that line and save.
Step 13: Getting Setup on Games Repository for Learning Java by Programming a Board Game
Programming a board game is a great way to learn Object Oriented Programming and Java. It has been somewhat of a tradition at IHMC Robotics to have interns and new hires program a game before delving into production code so that they are set up well, understand some good programming habits and practices, get experience with code repositories, and gain confidence to be able to contribute to the code base. There are two choices when pulling in new repositories. One is to add the new repositories to your other pulled code so it's all in the same place. Another option is to create a new directory of code and a new Workspace and have some projects in one of the directories and the games in the other. This method of breaking them into two can be preferable so that you don't have to worry about issues in one to use the other and also since it will compile faster. We'll use the method of separate directories and workspaces here:
- Create a New WorkSpace by going to File→Switch Workspace→ Other. Click the three buttons under copy settings (Workbench Layout, Working Sets, Preferences). Give it a new name like JavaGamesWorkspace. Click on Launch.
- Once it is created, remove the old repositories. To do so, go to the Git Perspective. Right click on each repository and select Remove Repository From View. Do not select Delete. They are still on your drive and used by your old Workspace. You just won't have them used in this workspace where you'll just have the code required for games.
- Create a new directory for your new set of repositories. For example, create C:/repos-games.
- Similar to the Step Above (Clone IHMC Code Repositories), you'll need to do some steps to Clone three repositories. Reread those steps above if you are not sure, but don't clone those repositories. Instead, clone the three repositories below. This time make sure the local directory for repository-group is set to C:/repos-games/ and for the other two repositories, make sure their local directory is set to C:/games-repos/repository-groups
- Clone the repository-group repository, with the local directory set to C:/games-repos/
- (As described in the steps above, you can click the following link to get to the repo, then in the web page click on the Clone Repo button, then CTRL-C the name, and then in Eclipse, click the Clone Repository Button) https://bitbucket.ihmc.us/scm/libs/repository-group.git
- Clone the following repositories and put them in the local directory C:/games-repos/repository-groups:
- Once you pull the code, Import Gradle Project, same as before. (File→Import → Gradle → Existing Gradle Project).
- Go through the steps to import the gradle project.
- Go to the Java Perspective. CTRL-SHIFT-T to find a games class, such as Connect4Game. Run it to make sure it comes up and all is good. Type in Y and hit return in the Console to tell it you'll play the computer. Play the computer and beat it. If you can't try again.
- Explore the various games that have been written over the years. Note where there is bad looking code and where there is good (lots of each is available in this repository. Try to only add good if you can...)
- Run OthelloSpriteWorldGUI and play a game against a friend. Othello is an ok example of some ok written code, and is an example of how you can use JavaSpriteWorld to quickly do the GUI for a game. Unless you are going to be a graphics developer, you should NOT try to write the graphics for a game from scratch, or you'll spend a couple weeks on it. Instead, use a framework like JavaSpriteWorld that has most of the things you need set up for you so that you minimize headaches. If you do a game with dice and black and white pieces, just about everything is there for you already.
Step 14: Setup for Multiple Screen Operation
You'll want to use 2-3 monitors for Eclipse. If you only use 1 monitor for your computer, get a second monitor or more. If you don't think it is important, consider a different line of work.
- If you don't have two monitors or more monitors, get them and get them set up. Four is preferable if your computer can handle them.
- If you don't have a good keyboard and mouse, get them and get them set up.
- If you don't have a good desk and ergonomic setup that you like, get it and get it set up.
- Start Eclipse.
- Click on the Java Perspective Button in the upper right (or do Window->Perspective→Open Perspective→Other and Select the Java(default) perspective).
- There should be a bunch of views and such showing up. Click and drag on the Bar containing the Problems, Javadoc, and Declaration View tabs and drag it to another monitor. A new window will show up with just those tabs in it.
- Drag the other bars into the new window; all except for the cod bar. Leave that in the original window. Maximize the new window and rearrange the bars nicely and sizing the various sections the way you like them. Below is how Jerry sets it up:
- If you don't have the following views, they might be helpful: Package Explorer, Problems, Console, Progress, Tasks, Breakpoints, JUnit, Debug, Play around and look through the other potential views and see if they would be good to put in the second window.
- Only the Code Tabs should be in the first window. Anything else move out to the second window.
- On the Perspective Button in the upper right, right click and select Save As... Give it a good name, like JerryJava.
- Close the original Java Perspective Button by right clicking on it and select close.
- Close Eclipse and Restart it and make sure that it defaults to your new perspective.
- Repeat the process above with the Git Perspective. For this one I like to do 3 windows. One with Code, Search Console, Etc. and the Git Repositories. One with only the history view tab. And one with Git Staging Tab.
- Save that perspective with a good name and close the original Git perspective. Restart eclipse and make sure that the perspectives are set up correctly.
- If you ever accidentally mess up a window, you can right click on the perspective and Select "Reset". That will bring it back to the state in which you last saved it.
- IF you make more changes later, remember to right click and Save As... to save your perspective.
Step 15: Git through Eclipse
- The instructions here are pretty good: Eclipse EGit VCS Plugin
- Follow them the best you can. Ask Jerry or Duncan for help. If you find errors on that page, fix them.
Step 16: JavaFX, SceneBuilder, etc. (Optional. Not needed for Getting started or Learning Java by Programming a Game.)
If you are going to do any GUI layout, it is best to use good tools. SceneBuilder is one of these. You'll need to incorporate JavaFX into Eclipse:
- Read over the instructions at https://www.eclipse.org/efxclipse
- Install e(fx)clipse by running Eclipse and going to Help→Eclipse Marketplace and searching for JavaFX.
- Click on Install. Accept licenses. Etc. Restart Eclipse.
The following is to configure Eclipse for using SceneBuilder that is GUI design tool. If you think you will not be designing GUIs, then you can skip the following and jump to Step 16.
- Download and Install SceneBuilder for Java 8 Windows 64 bit install from Gluon at https://gluonhq.com//products/scene-builder/
- It'll automatically run. Kill it.
- In Eclipse, go to Window->Preferences→JavaFX and enter where the SceneBuilder executable got installed.
- Apply and Close.
- Now you should be able to find a fxml file in the Package Explorer and right click on it and say Open with Scene Builder.
- When you get to the point where you might want to do some GUI layout, find a good tutorial and go through it. One good looking one is at https://code.makery.ch/library/javafx-tutorial/
- There are also lots of video tutorials for SceneBuilder. Here are a good playlist of JavaFX in general, with Scene Builder about 34 into the list:
- To see some good examples of JavaFX in action, install and Run Ensemble8. You can run it from a WebStart application by clicking on the link at https://www.oracle.com/technetwork/java/javase/overview/javafx-samples-2158687.html You can also get an executable jar file from there too. Or try this one: Ensemble8.jar
Step 17: Stash Username and Password in Gradle Properties (Optional. Not needed for Getting started or Learning Java by Programming a Game.)
- In order to install some of the closed source software, you need to have your Stash username and password in a file on your computer.
- Find and open in a text editor $HOME/.gradle/gradle.properties, where $HOME is where Windows puts your files. For example, C:\Users\jerry\.gradle\gradle.properties
- If that file does not exist, create it.
- Add the line: artifactoryUsername=jpratt (substituting your username) and the line artifactoryPassword=password (substituting your password).
Step 18: Running the Atlas "Whole Enchilada" Simulation (Optional. Not needed for Getting started or Learning Java by Programming a Game.)
- As in the steps above for cloning a repository, clone the additional following repositories. Make sure to put them all in the repository-group location:
- Do Gradle Refresh and build the project. These will each take a few minutes.
- Check the Problems Tab when done building to see if any errors. If so, try to figure them out and if cannot, make sure to go over all the previous instructions to make sure you didn't do anything wrong. If still can't figure it out, ask Jerry to fix these instructions.
- Go to DDS Domain ID Registry and find your Domain ID. If not listed, choose a new one and add it. Make sure different than others or you will break stuff.
- Run NetworkParametersCreator. Set most of the things to localhost (127.0.0.1) as in the picture, with ROS master URL http://127.0.0.1:11311. Set the RTPSDomainID on the bottom to be the one assigned to you (replace -1).
- Click Save.
- Run AtlasObstacleCourseDemo. This will bring up a Launch window. Drop down DEFAULT on the location. Make sure the following check boxes are checked: Simulation, SensorModule, NetworkProcessor. Click OK.
- This will bring up an SCS simulation with Atlas. Make sure it seems to be running ok, by plotting t.
- Run AtlasOperatorUserInterface. Wait for it to come up and make sure you can see the camera view on the left side.
- Play around with the interface.
- Click the third button on the LIDAR Control buttons to show LIDAR.
- Once LIDAR shows up some, right click on the ground in the right viewport to have some footsteps show up. Click space to take the footsteps.
- Play around by clicking things and figuring it out. You can't break things. That's the beauty of simulation.
- Run LidarBasedREAStandaloneLauncher. This will run REA and bring up a GUI. Use the middle mouse wheel to zoom out.
- Watch and be amazed as Planar Regions appear. Click on the Octree tab and the clear button to erase them and watch them form again.
- In AtlasOperatorUserInerface click the third LIDAR button again to hide LIDAR points and click the fifth button to show the planar regions. Be amazed as they show up in the UI!
- Click on the SNAP button on Footstep Controls. Now when you right click on a planar region, the footsteps should snap to the planar region.
- AtlasOperatorUserInterface is the interface we used for the DRC and still use a lot for many things. You can keep it running as you try the things below, but if you're computer lags, you also can kill it but keep REA running.
- Run AtlasFootstepPlannerUI. Another GUI will pop up. Make sure "Accept New Planar Regions" check box is clicked in the Main tab. Zoom out and center on the robot and planar regions. Use Shift-Click to center and ASDW to navigate.
- Click on Place Goal. Place the Goal and the heading direction in the UI somewhere. Click Compute Path. Be amazed as footstep path is generated. Click on send plan to send it.
- Play around more. Once you are comfortable, find when someone is running a robot next and ask them to give you a lesson on how to operate it. Practice in sim first.
- If your sims are sluggish and you are going to be doing a lot of development, probably should get a faster computer. To speed some things up, do the following:
- In AtlasObstacleCourseDemo, set recordFrequencySpeedup = 10 (or even 100 if you wish) and AtlasRobotVersion version = AtlasRobotVersion.ATLAS_UNPLUGGED_V5_NO_HANDS;
- *** Do not check those changes in to the repository. Only change them locally. ***
- If you want to walk on stairs or partial contacts, set addExtraContactPoints = true; Otherwise, keep it false.
- Set SwingTime lower (say 0.6) and TransferTime (say 0.1) in the GUIs.
- Run AtlasBehaviorUIAndModule. Play around with the behaviors.