CrateDB is written in Java and includes a pre-configured bundled version of OpenJDK in its build. But to develop CrateDB, you still have to install Java in order to run the Maven build tool. Some of the tools that are used to build documentation and run tests require Python.
To set up a minimal development environment, you will need:
Then, clone the repository and navigate into its directory:
$ git clone https://github.com/crate/crate.git $ cd crate
If you want to ignore commits (i.e. bulk code formatting) when watching blame history please issue the following:
$ git config blame.ignoreRevsFile .git-blame-ignore-revs
If you'd like to just ignore them for a single run of git blame:
$ git blame --ignore-revs-file .git-blame-ignore-revs
This project uses Maven as a build tool. The most convenient way to build and run CrateDB while you are working on the code is to do so directly from within your IDE. See the section on IDE integration.
However, you can also use Maven directly. Maven can be invoked by executing
./mvnw. The first time this command is executed, it is bootstrapped
automatically and there is no need to install Maven on the system.
To compile the CrateDB sources, run:
$ ./mvnw compile
To build the CrateDB distribution tarball, run:
$ ./mvnw package -DskipTests=true
The built tarball will be in:
./app/target/
And then start CrateDB like this:
tar xvzf app/target/crate-*.tar.gz ./crate-*/bin/crate
If you want to attach a debugger to the instance, you'd have to enable the debug agent:
export CRATE_JAVA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005"
Then create an "Attach" configuration in your IDE or editor. If using Visual Studio Code you can use the pre-defined "Attach to CrateDB" configuration.
To import the project into IntelliJ IDEA, first build the sources outside of your IDE with:
$ ./mvnw clean install -DskipTests=true
Then import the project into IntelliJ. You may need to explicitly reload maven projects to ensure that it correctly picks up generated source files from antlr.
Finally, run a git clean to remove pointless IntelliJ file changes to checked in config files.
Refer to Tests cheatsheet.
If you use IntelliJ, there is a Checkstyle plugin available which lets you check Checkstyle compliance from within the IDE.
The Checkstyle plugin enforces rules defined in <PROJECT_ROOT>/checkstyle.xml. It checks for things such as unused imports, inconsistent formatting, and potential bugs.
To run checkstyle with maven, use:
./mvnw compile checkstyle:checkstyle
You can create test coverage reports with jacoco by running:
$ ./mvn test jacoco:report
The test coverage report (in HTML) can then be found in
<module>/target/site/jacoco/index.html.
To run the Forbidden APIs tool:
$ ./mvnw compile forbiddenapis:check
If you want to work on a release branch (e.g.: 5.2) you can use
git worktree to avoid checking out the branch in the same directory you've
imported to your IDE as master. This can be handy especially if the release
branch uses older Java, Lucene, etc. or if there are changes in the layout of
the projects, as you won't need to wait for your IDE to switch between the two
branches (workspaces). Inside your crate repo:
$ git checkout -b 5.2 --track origin/5.2 $ git checkout master $ git worktree add ../crate-5.2 5.2
This way you can have a crate-5.2 (or whatever name you choose) in the same
directory level as your crate (master) repo. You can work on it
independently of master and import it as a separate project in your IDE. Of
course you can use the git worktree for any branch that you want to work on
independently of master. If you want to remove a worktree, simply issue the
following from inside your main crate repo:
$ git worktree remove ../crate-5.2
If you pulled in some new commits and are getting strange compile errors, try to reset everything and re-compile:
$ git clean -xdff $ ./mvnw compile