How to set up a build environment from scratch

Introduction

This article is aimed at people without Java (or Maven) development experience who would nevertheless like to build the project themselves.

It takes you from nothing to a full working development environment so more experienced developers will be able to skip several steps.

Step 1 - Creating a basic development environment (Java, Maven, Git)

If you're using Windows you'll find much of this software has a standard installer. For OS X I would strongly urge you to install Homebrew and Linux has a variety of standard package managers such as rpm, yum and apt-get.

Install Java

Get the latest JDK for your operating system.

• Open JDK is an excellent choice for Linux users.
• Oracle's download site if you're on Windows or OS X and ensure you don't tick any boxes that will install various adware banners or the NetBeans IDE etc.

Install Maven

Get the latest Maven, which will handle all your build requirements. If you're on OS X and using Homebrew then you can install with brew install maven.

If you're not familiar with it, the key difference is that Maven builds your project and pulls in all the required dependencies from either a local repository of JARs or off the internet if it can't find them locally.

To verify that Maven is installed and working, do the following at the command line:

mvn --version

You should get a report that looks a bit like this:

Apache Maven 3.6.3 (cecedd343002696d0abb50b32b541b8a6ba2883f)
Maven home: /usr/local/Cellar/maven/3.6.3_1/libexec
Java version: 14.0.1, vendor: N/A, runtime: /usr/local/Cellar/openjdk/14.0.1/libexec/openjdk.jdk/Contents/Home
Default locale: en_GB, platform encoding: UTF-8
OS name: "mac os x", version: "10.15.6", arch: "x86_64", family: "mac"

Install Git (and set up a GitHub account)

Git keeps track of all changes to text and binary files so that you can always go back to earlier versions. I use it to keep track of all code changes and to link those changes to Issues that users report to me.

Now is a good time to register for GitHub account if you haven't already done so. Even if you're not a developer having a GitHub account will allow you to keep track of open source projects that you've contributed to (good for your CV/resume) and you may find Git itself useful for your own day to day work - it's extremely flexible.

Install Git. On OS X with Homebrew a simple brew install git is sufficient.

To verify that Git is installed and working, do the following at the command line:

git --version

You should get a report that looks a bit like this:

git version 2.26.2

Step 2 - Building at the command line

Most open source projects in GitHub provide a README.md file that offers build instructions aimed at developers familiar with the underlying technologies. This section will take you through this process with more detail.

Clone the project repository with the following command:

cd <where you want the code>
git clone https://github.com/gary-rowe/hid4java
cd hid4java
git checkout develop

Git will provide a lot of information about what is being downloaded and the progress it is making. The repository can take a bit of time to arrive the first time, but subsequent updates are nearly instant. Many open source projects use the develop branch as their day-to-day working branch with master being for production releases. This is the git-flow process.

This clone of the project repository is entirely under your control. You can make any changes you like to it. However, you won't have the ability to push those changes back upstream to our repository so don't worry about making breaking changes, you can always revert back to the latest known good position using

git reset --hard HEAD

The above command will wipe out all your local changes and take you back to the last update (pull) you made which should always be a good build.

Verify that the application builds using a terminal (always fall back to the terminal if in doubt):

mvn clean install

You will find that Maven downloads the world during its initial build. Once it has those artifacts (JARs, WARs etc) then it won't download them again, unless you delete them. Typically these files are placed in your user home directory under .m2/repository which may be a hidden directory on your operating system.

After completion you should see a large "build successful" report. If not you can check the project's README file for an indication of the current build status.

Step 3 - Install Intellij

Now that you've got Git and Maven working you can choose an IDE. Personally, I love Intellij and I would strongly urge you to get the community edition.

During installation you'll be asked to install a zillion plugins, make sure you include Git and Maven and anything that you recognise. You can always enable/disable these later so just blindly accepting defaults will be fine but might slow down the IDE startup.

After installing fire it up and do the following:

Importing a project into Intellij

• Use File | Import Project and locate the project pom.xml (it's in the project root on the develop branch).
• Work through the various dialogs just accepting whatever Intellij suggests
• In the bottom right of the screen you'll see the git branch listed (develop if you checked it out earlier), you can click to check out another branch

Run some code

• Use the Project flyout on the left border to locate src/test/java.
• Dig deeper to find org/hid4java/examples and the UsbHidEnumerationExample.
• Right click and look for the entry with a green triangle next to Run UsbHidEnumerationExample
• Select this option which will run that example

If all goes well you should see a list of devices that are currently attached to the machine.

If you encounter problems then please refer to the Troubleshooting pages.