How To Setup Your Knowm Developer Environment

Introduction

This document will help you get up and running with your own development environment compatible with Knowm’s development stack. There’s a bit of a learning curve, but we’ve taken measures to make collaborating as easy as possible. Each section in this document will list the motivation for each component and list alternatives. You should feel free to use whatever tools you prefer, but if you’re completely new, this document will guide you to getting started using the tools that we use. Because everyone uses different computers and operating systems, it’s impossible to provide step by step instructions for installing every tool on every system. Plus, there already exists how-to guides for installing tool X on system Y all over the Internet.

Mac OSX

At Knowm, we primarily use OSX on our development machines. You can develop on Windows or Linux, as all tools needed are cross platform. A lot of the basic principles are the same. Some how-tos will be geared towards Linux, especially for server-based applications.

If you are using OSX but have not used Homebrew now is a good time to learn it. Most instructions for installing software will use Homebrew.

GitLab (Private) and GitHub (Public)

At the most basic level, GitLab and GitHub are just a service that hosts our git project repositories in a centralized place. Everyone with access to the repos can view and push code. More advanced features that we use GitLab for are access management and the Issues page. If anyone has any questions, it is highly preferred to post the question on the project’s issue page. That way, everyone can benefit from the question and answer and participate in the conversation. Issues can also be created for feature requests and bug reports.

Instead of allowing everyone with access to a project repo to push code changes, pull requests will be used instead. If a contributor issues a pull request, the project’s committers are notified. At that point they can review the code that was submitted, and “accept” it after review. If there are problems with the code, the reviewer can leave comments. After a round of comments and updates, the pull request can be finally merged into the repo. Project owners and committers don’t need to submit pull requests, as they can push code directly.

SourceTree

SourceTree pulls and pushes code. It is a git client. There is plenty of documentation out there on git and all of its capabilities, but for the sake of this introduction, we will concentrate on the basics. SourceTree is a nice GUI-based git client that is cross-platform and is updated frequently. You need to install SourceTree on your computer. It installs git for you as well, so you won’t have to install git yourself separately.

Cloning vs. Forking

Cloning If you are a repo owner or committer (direct write access) or you are only interesting in reading the project’s code, you should clone a repo. When you clone a repo, you’re creating an exact copy of a remote repo on your local computer. Using SourceTree, you can commit your edits/updates to your local clone, and then push the commits to the remote repo.

Forking If you are a contributor (no write access) and you plan on contributing changes back to the repo, you should fork a repo. When you fork a repo, you are creating an exact copy of the remote repo on GitLab. That repo is now yours, and separate for the original repo. You then need to clone your forked repo to create an exact copy of a remote repo on your local computer. To contribute code back to the original repo, you first need to push commits to your fork and then submit a pull request via the GitLab website.

Java

Java is the code. There are plenty of other sources you can find for more information about Java. We recommend to Java beginners the book Head First Java, 2nd Edition. Even though it’s old, it’s still a great intro and all the code in the book will work with the latest Java versions. There are thousands of Java tutorials out there. For Knowm projects, we use Java 7 or higher, so make sure you have at least Java 7 installed.

You need to install Java on your computer if it is not already there.

Eclipse

Eclipse helps you code. Eclipse is an IDE (integrated developer environment). While you could (and some people prefer to) edit all your source files in a basic text editor, compile and run you programs from the command line, Eclipse attempts to make the process easier. Other features of an IDE include refactoring tools, debuggers, classpath management, and specialized file type editors, and the number of extra plugins is enormous. Another popular alternative Java IDE is IntelliJ.

Maven

Maven manages dependencies and compiles your code. Most software projects utilize 3rd-party dependencies. In Java, these dependencies are in the form of compiled jars. Without Maven, you’d need to manually hunt down jars on the Internet and manually add then to your project and project’s classpath. Using Maven, you simply define with dependencies your project has in a file called pom.xml placed at the root of the project. Maven then fetches the necessary jars and adds then to your project. Additionally, Maven will build your project for you with simple commands such as mvn package, which creates a jar out of your project if desired.

m2e is a Eclipse plugin that integrates Maven into Eclipse.

You need to install the m2e plugin into Eclipse. m2e has its own embedded maven installation, so you won’t have to install maven yourself separately. In Eclipse, go to Help –> ‘Eclipse Marketplace…’ and search for ‘Maven’. Click on ‘Install’ for the m2eclipse plugin title ‘Maven Integration for Eclipse (Mars) 1.6.1’.