Prerequisites
Building Cassandra from source is the first important step in contributing to the Apache Cassandra project.You will need to install Java (JDK 8 or 11, depending on which versionyou want to build Cassandra against, best is to install both and thenswitch between them when needed), Git, and Ant (including ant-optional).
Getting the source code
The source code for Cassandra is shared on the central Apache Gitrepository and organized by branch, one branch for each major version.You can access the code for the current development branch atgitbox.apache.org/repos/asf/cassandra.git (the primary location)or at github.com/apache/cassandra (a mirror location).
However, to develop a patch or a new feature, you should fork the Cassandraproject first and then clone it from your own fork:
git clone https://github.com/<your_git_name>/cassandra.git cassandraBuilding Cassandra
Cassandra is a Java project which is built using Ant.The build file, build.xml located in the root of the project content,has various tasks defined (you can list all of them with some shortdescriptions by running ant -p).
The build uses the Java compiler which is currently set up in yourshell. By default, the build uses Java 8. If you want to buildwith Java 11, you need to either add a build property -Duse.jdk11=trueto your Ant build command or export the environment variableCASSANDRA_USE_JDK11=true. Otherwise, if you run the build usingJava 11, the build script complains.
Now you can build Cassandra with the default task - just executeant or ant jar. This may take a significant amount of time dependingon artifacts that have to be downloaded or the number of classes thatneed to be compiled. When the build completes, you can find a JAR filein the build directory, and the database service can be started withthe bin/cassandra script.
Building a distribution
Some tasks you might be interested in are:
build- compile the production code without producing any JARsbuild-test- compile the test code without producing any JARsartifacts- generate Cassandra distribution inbuild/distdirectory and package it totar.gz(with and without sources)mvn-install- generatecassandra-allJAR artifact along withsources and JavaDoc, and install it in the local Maven repositoryrealclean- clean the project from any build products, as well asfrom any dependencies (in fact that means removingbuildandlibdirectories)
Hint Remember to clean the project after switching branches as build artifactsare versioned. |
There are other tasks related to testing, and they are covered inTesting section.
Setting up Cassandra in IntelliJ IDEA
IntelliJ IDEA by JetBrains is one ofthe most popular IDEs for Cassandra and Java development in general.The Community Edition can be freely downloaded with all features needed to get started developing Cassandra.
Use the following procedure for Cassandra 2.1.5+:
Generate project files by executing the following target from Ant build:
ant generate-idea-filesStart IDEA.
Open the IDEA project from the checked-out Cassandra directory using
File > Openin IDEA’s menu.
The project generated by ant generate-idea-files containsnearly everything you need to debug Cassandra and execute unit tests.
Hint Although you do not need to build the project with |
You should be able to:
Run/debug defaults for JUnit
Run/debug configuration for Cassandra daemon
Read/modify the license header for Java source files
Study Cassandra code style
Inspections
Hint If you wish to work with older Cassandra versions, see our wiki for instructions. |
Opening Cassandra in Apache NetBeans
Apache NetBeans is the elder of the open sourced java IDEs,and can be used for Cassandra development.There is no project setup or generation required to open Cassandra in NetBeans.Use the following procedure for Cassandra 4.0+.
First, clone and build Cassandra.Then execute the following steps to use NetBeans.
Start Apache NetBeans
Open the NetBeans project from the ide/ folder of thechecked-out Cassandra directory using
File > Open Projectin NetBeans' menu.
You should be able to:
Build code
Run code
Debug code
Profile code
These capabilities use the build.xml script.Build/Run/Debug Project are available via the Run/Debug menus, or theproject context menu.Profile Project is available via the Profile menu. In the openedProfiler tab, click the green "Profile" button.Cassandra’s code style is honored in ide/nbproject/project.properties.The JAVA8_HOME system environment variable must be set for NetBeans to execute the Run/Debug/Profile ant targets to execute.
Setting up Cassandra in Eclipse
Eclipse is a popular open source IDE that can be used for Cassandradevelopment. Various Eclipse environments are available from thedownload page. Thefollowing guide was created with "Eclipse IDE for Java Developers".
These instructions were tested on Ubuntu 16.04 with Eclipse Neon (4.6)using Cassandra versions 2.1 through 3.x.
First, clone and build Cassandra.Then execute the following steps to use Eclipse.
Generate the IDEA files using ant:
ant generate-eclipse-filesStart Eclipse.
Open the Eclipse project from the checked-out Cassandra directory using
File > Import > Existing ProjectsandWorkspace > Selectgit directory.Select the correct branch, such ascassandra-trunk.Confirm and select
Finishto import your project.
Find the project in Package Explorer or Project Explorer.You should not get errors if you build the project automatically using theseinstructions. Don’t set up the project before generating the files with ant.
You should be able to:
Run/debug defaults for JUnit
Run/debug Cassandra
Study Cassandra code style
Unit tests can be run from Eclipse by simply right-clicking the classfile or method and selecting Run As > JUnit Test.Tests can be debugged by defining breakpoints (double-click line number) andselecting Debug As > JUnit Test.
Alternatively all unit tests can be run from the command line asdescribed in testing.
Debugging Cassandra Using Eclipse
There are two ways to start a local Cassandra instance with Eclipse for debugging.You can either start Cassandra from the command line or from within Eclipse.
Debugging Cassandra started at command line
Set environment variable to define remote debugging options for theJVM:
export JVM_EXTRA_OPTS="-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=1414"Start Cassandra by executing the
./bin/cassandra
Next, connect to the running Cassandra process by:
In Eclipse, select
Run > Debug Configurations.
Create new remote application.
Configure connection settings by specifying a name and port 1414.Confirm
Debugand start debugging.
Debugging Cassandra started from Eclipse
Cassandra can also be started directly from Eclipse if you don’t want touse the command line.
In Eclipse, select
Run > Run Configurations.
Create new application.
Specify name, project and main class
org.apache.cassandra.service.CassandraDaemon
Configure additional JVM specific parameters that will start Cassandrawith some of the settings created by the regular startup script. Changeheap related values as needed.
-Xms1024M -Xmx1024M -Xmn220M -Xss256k -ea -XX:+UseThreadPriorities -XX:ThreadPriorityPolicy=42 -XX:+UseParNewGC -XX:+UseConcMarkSweepGC -XX:+CMSParallelRemarkEnabled -XX:+UseCondCardMark -javaagent:./lib/jamm-0.3.0.jar -Djava.net.preferIPv4Stack=true
Confirm
Debugand you should see the output of Cassandra start up in the Eclipse console.
You can now set breakpoints and start debugging!
General notes
You may sometimes encounter some odd build failures when running the ant commands above. If you do, start ant with the realclean option:
ant realcleanRemember that all the tasks mentioned above may depend on building source files. If there are actual compilation errors in the code, you may not be able to generate project files for IntelliJ Idea, Netbeans, or Eclipse.It is especially important that you have imported the project adequately into IDE before doing merges or rebases. Otherwise, if there are conflicts, the project cannot be opened in IDE, and you will be unable to use any fancy conflict resolution tools offered by those IDEs.
