Contributor Tools

    We recommend using either Eclipse or IntelliJ IDEA to contribute to Alluxio. Instructions for setting up both IDEs can be found below.

    You can generate an Eclipse configuration file by running:

    Then import the folder into Eclipse. You may also have to add the classpath variable M2_REPO by running:

      IntelliJ IDEA

      To use IntelliJ IDEA to contribute to Alluxio, simply open IntelliJ and select “Import existing project”. Then select the “Maven” project type from the IntelliJ dialog. IntelliJ’s default configuration works without any modifications.

      After successfully importing your local Alluxio repo into IntelliJ, you may need to add the Maven profile ‘developer’ in order to avoid import errors.

      You can do this by going to

      And then check the box next to “developer” in the window pane.

      Run Alluxio processes within IntelliJ IDEA

      1. Run dev/intellij/install-runconfig.sh
      2. Restart IntelliJ IDEA

      3. Edit conf/alluxio-site.properties

        1.   alluxio.home={alluxio.home}
        2.   alluxio.master.hostname=localhost
        3.   alluxio.master.journal.type=UFS
        1.   log4j.rootLogger=INFO, ${alluxio.logger.type}, ${alluxio.remote.logger.type}, stdout
        2.   log4j.threshold=ALL
        3.   log4j.appender.stdout=org.apache.log4j.ConsoleAppender
        4.   log4j.appender.stdout.layout=org.apache.log4j.PatternLayout
        5.   log4j.appender.stdout.layout.ConversionPattern=%d{ISO8601} %-5p %c{2} (%F:%M(%L)) - %m%n

      5. Format the Alluxio master by running bin/alluxio formatMaster

      6. In Intellij, start Alluxio master process by selecting Run > Run > AlluxioMaster
      7. Prepare the RamFS and format the Alluxio Worker with bin/alluxio-mount.sh SudoMount && bin/alluxio formatWorker
      8. In Intellij, start Alluxio worker process by selecting Run > Run > AlluxioWorker
      9. Verify the Alluxio cluster is up as Running Alluxio Locally

      Before pushing changes or submitting pull requests, we recommend running various maven targets on your local machine to make sure your changes do not break existing behavior.

      For these maven commands we’ll assume that your command terminal is located in the root directory of your local copy of the Alluxio repository.

      1. $ cd ${ALLUXIO_HOME}

      To make sure your code follows our style conventions you may run. Note that this is run any time you run targets such as compile, install, or .

      1. $ mvn checkstyle:checkstyle

      FindBugs

      Before submitting the pull-request, run the latest code against the findbugs Maven plugin to verify no new warnings are introduced.

      To simply compile the code you can run the following command:

        This will not execute any unit tests but will execute maven plugins such as checkstyle and findbugs.

        To speed up compilation you may use the following command:

        1. $ mvn -T 2C compile -DskipTests -Dmaven.javadoc.skip -Dfindbugs.skip -Dcheckstyle.skip \
        2.   -Dlicense.skip -pl '!webui'

        This command will skip many of our checks that are in place to help keep our code neat. We recommend running all checks before committing.

        • -T 2C runs maven with
        • -DskipTests skips running unit and integration tests
        • -Dmaven.javadoc.skip skips javadoc generation
        • -Dfindbugs.skip skips findbugs execution
        • -Dcheckstyle.skip skips code-style checking
        • -Dlicense.skip skips checking files for license headers
        • -pl '!webui' skips building the Alluxio UI module. If this module isn’t compiled then the UI cannot be accessed locally.

        You may replace the compile target in the above command with any other valid maven target to skip checks as well. The targets compile, verify, and install are typically the most useful.

        Creating a Local Install

        If you want to test your changes with a compiled version of the repository, you may generate the jars with the Maven install target. The first time Maven executes it will likely need to download many dependencies. Please be patient as the first build may take a while.

        1. $ mvn -T 2C install -DskipTests

        Run all unit and integration tests

        1. $ cd ${ALLUXIO_HOME}
        2. $ mvn test

        This will use the local filesystem as the under storage.

        Run a single unit test

        1. $ mvn -Dtest=<AlluxioTestClass>#<testMethod> -DfailIfNoTests=false test

        Run unit tests for a specific module

        You can execute the command targeting the desired submodule directory. For example, to run tests for HDFS UFS module you would run

        Run unit tests for HDFS UFS module with a different Hadoop version

        1. # build and run test on HDFS under storage module for Hadoop 2.7.0
        2. $ mvn test -pl underfs/hdfs -Phadoop-2 -Dhadoop.version=2.7.0
        3. # build and run test on HDFS under storage module for Hadoop 3.0.0
        4. $ mvn test -pl underfs/hdfs -Phadoop-3 -Dhadoop.version=3.0.0

        The above unit tests will create a simulated HDFS service with a specific version. To run more comprehensive tests on HDFS under storage using a real and running HDFS deployment:

        1. $ mvn test -pl underfs/hdfs -PufsContractTest -DtestHdfsBaseDir=hdfs://ip:port/alluxio_test

        Redirect logs to STDOUT

        To have the logs output to STDOUT, append the following arguments to the mvn command

        1. -Dtest.output.redirect=false -Dalluxio.root.logger=DEBUG,CONSOLE

        Test FUSE

        The FUSE tests are ignored if the libfuse library is missing. To run those tests, please install the libraries referenced in .

        Alluxio uses gRPC 1.28.1 for RPC communication between clients and servers. The .proto files defined in core/transport/src/grpc/ are used to auto-generate Java code for calling the RPCs on clients and implementing the RPCs on servers. To regenerate Java code after changing a gRPC definition, you must rebuild alluxio-core-transport module with 'generate' maven profile.

          Alluxio uses 3.12 to read and write journal entries. The .proto files defined in core/transport/src/proto/ are used to auto-generate Java definitions for the protocol buffer messages.

          To change one of these messages, first read about updating a message type to make sure your change will not break backwards compatibility. To regenerate Java code after changing a definition, you must rebuild alluxio-core-transport module with the 'generate' maven profile.

          1. $ mvn clean install -Pgenerate

          Please refer to for all available commands.

          Some commands have different prerequisites.

          All commands except bootstrapConf, killAll, copyDir and clearCache will require that you have already built Alluxio (see Build Alluxio Master Branch about how to build Alluxio manually).