blob: 60f25d5d277942fb25989183b9d253c365722779 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership.
The ASF licenses this file to You under the Apache License, Version 2.0
(the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
See the License for the specific language governing permissions and
limitations under the License.
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="/css/bootstrap.min.css" rel="stylesheet">
<link href="/css/bootstrap-theme.min.css" rel="stylesheet">
<link href="/css/dataTables.bootstrap.css" rel="stylesheet">
<link href="/css/pirk.css" rel="stylesheet" type="text/css">
<link href="//" rel="stylesheet">
<title>For Developers</title>
<script src=""></script>
<script src="/js/bootstrap.min.js"></script>
<script src="/js/jquery.dataTables.min.js"></script>
<script src="/js/dataTables.bootstrap.js"></script>
// show location of canonical site if not currently on the canonical site
$(function() {
var host =;
if (typeof host !== 'undefined' && host !== '') {
// decorate menu with currently navigated page
$(function() {
$(function() {
// decorate section headers with anchors
return $("h2, h3, h4, h5, h6").each(function(i, el) {
var $el, icon, id;
$el = $(el);
id = $el.attr('id');
icon = '<i class="fa fa-link"></i>';
if (id) {
return $el.append($("<a />").addClass("header-link").attr("href", "#" + id).html(icon));
// configure Google Analytics
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
ga('create', 'UA-81114308-1', 'auto');
ga('send', 'pageview');
<body style="padding-top: 100px">
<nav class="navbar navbar-default navbar-fixed-top">
<div class="container-fluid">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#navbar-items">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<a href="/"><img id="nav-logo" alt="Apache Pirk" class="img-responsive" src="/images/pirkImage.png" width="150"/></a>
<div class="collapse navbar-collapse" id="navbar-items">
<ul class="nav navbar-nav">
<li class="nav-link"><a href="/downloads">Download</a></li>
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Documentation<span class="caret"></span></a>
<ul class="dropdown-menu">
<li id="nav_users"><a href="/for_users">For Users</a></li>
<li id="nav_developers"><a href="/for_developers">For Developers</a></li>
<li id="nav_developers"><a href="/cloud_instructions">Cloud instructions</a></li>
<li id="nav_papers"><a href="/papers">Papers &amp Presentations</a></li>
<li class="nav_faq"><a href="/faq">FAQ</a></li>
<li class="divider"></li>
<li><a href="/javadocs">Javadocs</a></li>
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Community<span class="caret"></span></a>
<ul class="dropdown-menu">
<li id="nav_getinvolvedpirk"><a href="/get_involved_pirk">Get Involved</a></li>
<li id="nav_listspirk"><a href="/mailing_list_pirk">Mailing Lists</a></li>
<li id="nav_peoplepirk"><a href="/people_pirk">People</a></li>
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Development<span class="caret"></span></a>
<ul class="dropdown-menu">
<li id="nav_releasing"><a href="/how_to_contribute">How to Contribute</a></li>
<li id="nav_releasing"><a href="/releasing">Making Releases</a></li>
<li id="nav_nav_verify_release"><a href="/verifying_releases">Verifying Releases</a></li>
<li id="nav_update_website"><a href="/website_updates">Website Updates</a></li>
<li><a href=" ">Issue Tracker/JIRA <i class="fa fa-external-link"></i></a></li>
<li><a href="">Jenkins Builds <i class="fa fa-external-link"></i></a></li>
<li><a href="">Travis CI Builds <i class="fa fa-external-link"></i></a></li>
<li><a href=""> Pirk Github Mirror <i class="fa fa-external-link"></i></a></li>
<li class="nav-link"><a href="/roadmap">Roadmap</a></li>
<ul class="nav navbar-nav navbar-right">
<li class="dropdown">
<a class="dropdown-toggle" data-toggle="dropdown" href="#">Apache Software Foundation<span class="caret"></span></a>
<ul class="dropdown-menu">
<li><a href="">Apache Homepage <i class="fa fa-external-link"></i></a></li>
<li><a href="">License <i class="fa fa-external-link"></i></a></li>
<li><a href="">Sponsorship <i class="fa fa-external-link"></i></a></li>
<li><a href="">Security <i class="fa fa-external-link"></i></a></li>
<li><a href="">Thanks <i class="fa fa-external-link"></i></a></li>
<li><a href="">Code of Conduct <i class="fa fa-external-link"></i></a></li>
<div class="container">
<div class="row">
<div class="col-md-12">
<div id="content">
<h1 class="title">For Developers</h1>
<li><a href="#general-info">General Info</a></li>
<li><a href="#code-repo">Code Repo</a></li>
<li><a href="#coding-standards">Coding Standards</a>
<li><a href="#apache-license-header">Apache License Header</a></li>
<li><a href="#author-tags">Author Tags</a></li>
<li><a href="#code-formatting">Code Formatting</a></li>
<li><a href="#ide-configuration-tips">IDE Configuration Tips</a>
<li><a href="#eclipse">Eclipse</a></li>
<li><a href="#intellij">IntelliJ</a></li>
<li><a href="#javadocs">JavaDocs</a></li>
<li><a href="#building">Building</a></li>
<li><a href="#continuous-integration">Continuous Integration</a></li>
<li><a href="#testing">Testing</a></li>
<li><a href="#debugging">Debugging</a></li>
<li><a href="#paillier-benchmarking">Paillier Benchmarking</a></li>
<li><a href="#release-process">Release Process</a></li>
<li><a href="#how-to-contribute">How To Contribute</a></li>
<h2 id="general-info">General Info</h2>
<p>Pirk is written in Java 8 and build and dependency management is accomplished via <a href="">Apache Maven</a>. Pirk uses <a href="">Git</a> for change management.</p>
<h2 id="code-repo">Code Repo</h2>
<p>The Pirk code is available via the <a href="">Pirk git repository</a> and is mirrored to <a href="">Github</a>.</p>
<p>To check out the code:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>git clone
<p>Then checkout the ‘master’ branch (which should be the default):</p>
<div class="highlighter-rouge"><pre class="highlight"><code>git checkout master
<h2 id="coding-standards">Coding Standards</h2>
<h3 id="apache-license-header">Apache License Header</h3>
<p>Always add the current ASF license header as described <a href="">here</a>. Please use the provided ‘eclipse-pirk-template.xml’ code template file to automatically add the ASF header to new code.</p>
<h3 id="author-tags">Author Tags</h3>
<p>Please do not use author tags; the code is developed and owned by the community.</p>
<h3 id="code-formatting">Code Formatting</h3>
<p>Pirk follows coding style practices found in the <a href="">eclipse-pirk-codestyle.xml</a> file; please ensure that all contributions are formatted accordingly.</p>
<h3 id="ide-configuration-tips">IDE Configuration Tips</h3>
<h4 id="eclipse">Eclipse</h4>
<li>Import Formatter: Properties &gt; Java Code Style &gt; Formatter and import the <a href="">eclipse-pirk-codestyle.xml</a> file.</li>
<li>Import Template: Properties &gt; Java Code Style &gt; Code Templates and import the <a href="">eclipse-pirk-template.xml</a>. Make sure to check the “Automatically add comments” box. This template adds the ASF header and so on for new code.</li>
<h4 id="intellij">IntelliJ</h4>
<li>Formatter <a href="">plugin</a> that uses eclipse code style xml.</li>
<h2 id="javadocs">JavaDocs</h2>
<p>Pirk Javadocs may be found <a href="/javadocs">here</a>.</p>
<h2 id="building">Building</h2>
<p>Pirk currently follows a simple Maven build with a single level pom.xml. As such, Pirk may be built via ‘mvn package’.</p>
<p>For convenience, the following POM files are included:</p>
<li>pom.xml — Pirk pom file for Hadoop/YARN and Spark platforms</li>
<li>pom-with-benchmarks.xml — Pirk pom file for running Paillier benchmarking testing</li>
<p>Pirk may be built with a specific pom file via ‘mvn package -f <specificpom.xml></specificpom.xml></p>
<h2 id="continuous-integration">Continuous Integration</h2>
<p>Pirk uses <a href="">Jenkins</a> for continuous integration. The build history is available <a href="">here</a>.</p>
<p>Pirk also uses <a href="">Travis CI</a> for continuous integration for Github Pull Requests; you can find the build history <a href="">here</a>.</p>
<h2 id="testing">Testing</h2>
<p>JUnit in-memory unit and functional testing is performed by building with ‘mvn package’ or running the tests with ‘mvn test’. Specific tests may be run using the Maven command ‘mvn -Dtest=<testname> test’.</testname></p>
<p>Distributed functional testing may be performed on a cluster with the desired distributed computing technology installed. Currently, distributed implementations include batch processing in Hadoop MapReduce and Spark with inputs from HDFS or Elasticsearch.</p>
<p>To run all of the distributed functional tests on a cluster, the following ‘hadoop jar’ command may be used:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>hadoop jar &lt;pirkJar&gt; org.apache.pirk.test.distributed.DistributedTestDriver -j &lt;full path to pirkJar&gt;
<p>Specific distributed test suites may be run via providing corresponding command line options. The available options are given by the following command:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>hadoop jar &lt;pirkJar&gt; org.apache.pirk.test.distributed.DistributedTestDriver --help
<p>The Pirk functional tests using Spark run via utilizing the <a href="">SparkLauncher</a> via the ‘hadoop jar’ command (not by directly running with ’spark-submit’).
To run successfully, the ‘spark.home’ property must be set correctly in the ‘’ file; ’spark-home’ is the directory containing ’bin/spark-submit’.</p>
<h2 id="debugging">Debugging</h2>
<p>Pirk uses <a href="">log4j</a> for logging. The file may be edited to turn allow a ‘debug’ log level.</p>
<h2 id="paillier-benchmarking">Paillier Benchmarking</h2>
<p>Pirk includes a benchmarking package leveraging <a href="">JMH</a>. Currently, <a href="/javadocs/org/apache/pirk/benchmark/PaillierBenchmark">Paillier benchmarking</a> is enabled in Pirk.</p>
<p>To build with benchmarks enabled, use:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>mvn package -f pom-with-benchmarks.xml
<p>To run the benchmarks, use:</p>
<div class="highlighter-rouge"><pre class="highlight"><code>java -jar target/benchmarks.jar
<p>Optionally, you can reduce the number of times each benchmark is run (default is 10) using the -f flag. For example, to run each benchmark only twice, use: ’java -jar target/benchmarks.jar -f 2’</p>
<p>FYI - Right now this spits out a lot of logging errors as the logger fails to work while benchmarks are running. Ignore the many stack traces and wait for execution to complete to see statistics on the different benchmarks.</p>
<h2 id="release-process">Release Process</h2>
<p>Please see <a href="/making_releases">Making Releases</a> and <a href="/verifying_releases">Verifying Releases</a>.</p>
<h2 id="how-to-contribute">How to Contribute</h2>
<p>Please see the <a href="/how_to_contribute">How to Contribute</a> page.</p>
<p><a href=""><img src="/images/feather-small.gif" alt="Apache Software Foundation" id="asf-logo" height="100" /></a></p>
<p>Copyright © 2016-2016 The Apache Software Foundation. Licensed under the <a href="">Apache License, Version 2.0</a>.</p>