Contributing to Apache MiNiFi C++

We welcome contributions to the Apache MiNiFi C++ project. We are providing this guide to make contributing easier and increase development. Apache MiNiFi is developed by an open community in which we welcome feedback and questions. You are invited to engage the community with questions at the dev or user list: dev@nifi.apache.org and user@nifi.apache.org.

Filing JIRA tickets

If you experience problems with Apache MiNiFi contact the dev E-mail list, above, or file an Apache JIRA Ticket [1]. Click Create button at the top and provide as much detail as you can to ticket description. Any information you can provide to facilitate replicating the problem is greatly appreciated.

If you wish to suggest new features, regardless if you have the time to provide the fix or implementation, we encourage you to file an Apache JIRA Ticket [1], providing as much detail as possible for the suggested feature.

Providing code or documentation contributions

Like all Apache projects, a mirror of the git repository is located at Github. The Apache MiNiFi C++ project is located at https://github.com/apache/nifi-minifi-cpp . The Apache NiFi ecosysem is Review Then Commit [2]. This requires the submission of pull requests (PRs [3])

Configuring your git client

Ensure your git user name and email are configured

 The following lines ensure your commits are appropriately annotated with your information

git config --global user.name "User Name"

git config --global user.email user.name@email.org

Checkout the 'master' or '0.x' branch

git checkout -b master origin/master will create a local, tracking branch named master.

git checkout -b 0.x origin/0.x will create a local, tracking branch named 0.x.

The master branch currently represents the next major release line (O.x).

Developing with MiNiFi C++

System Requirements

Utilities

• CMake
• 2.8 or greater
• gcc
• 4.8.4 or greater
• g++
• 4.8.4 or greater

Libraries / Development Headers

• libboost and boost-devel
• 1.48.0 or greater
• libleveldb and libleveldb-devel
• libuuid and uuid-dev
• openssl

Building

Apache MiNiFi C++ uses CMAKE [3]. To build the project you may run the following command:

mkdir ./build && cd ./build && cmake .. && make && make test && make linter

This will create the necessary build directory, create the CMAKE environment, make the project, run tests, and assess the code style with the provided linter. If your environment does not meet the necessary requirements your build will fail creating the CMAKE environment. E-mail dev@nifi.apache.org for help in installing necessary components.

 Dependencies

  The thirdparty directory contains some third party libraries used to build MiNiFi. We currently have the following dependencies:

• Catch – This is a C++ unit testing library
• Civetweb – Used for the ListenHTTP process in providing the ability to instantiate a webserver
• LevelDB – a key/value store that provides an ordered mapping of string keys to string values. This is used for the provenance and flow file repositories.
• Uuid – LibUUID provides us the ability to easily interact with UUID objects (RFC 4122 compliant )
• Yaml-CPP – Library that provides the capability to read YAML configuration files.
• Spdlog – C++ logging infrastruction
• OpenSSL – Provides TLS capabilities for communications.

Devlopment

Apache MiNiFi C++ can be developed in many IDEs, the scope of which are beyond this document. Common cross platform IDEs exist, such as CLion and Eclipse CDT. These IDEs offer the lowest bar of entry and the ability to continue development across platforms when switching environments.

Developing in Eclipse CDT
   To import Apache MiNiFi C++ into your Eclipse CDT environment, right click within your Project Explorer tab and import the Apache MiNiFi sub directory as an Existing AutoTools project. Click Browser to locate the existing directory, at which point Eclipse will populate the project name with nifi-minifi-cpp. Click Finish to complete the import process.

    Eclipse CDT will auto generate indices and populate auto complete. It is suggested that you build from the command line before committing to avoid any issues.

Developing in CLion

   Click File > Open Project and browser to the directory where you’ve stored the Apache MiNIFi C++ code base. Descend into the root directory of Apache MiNiFi C++ and click “Open.” CLion will auto detect the project. Follow prompts until you’ve imported Apache MiNiFI C++. CLion has a rich CMAKE environment allow you to debug within the environment. It is suggested that you build from the command line before committing to avoid any issues.

General Development Guidelines.

The project is structured with a main and libminifi directories. The former contains the MiNiFI C++ main entry point. The latter is a collection of source files that make up the CORE API.

For the include and src directories the following packages indicate the area of responsibility:

• libminifi/include/core

1. 1. Core contains the core components of the underlying API. Code within here represents the code that is required for all other components to function and contains base objects used within core

• libminifi/include/core/logging

1. 1. Contains the logging infrastructure.

• libminifi/include/core/yaml

1. 1. YamlConfiguration class. Exists in a separate directory so YAML-CPP can be ecluded for certain build configurations.

• libminifi/include/io

1. 1. Input and Output classes that are used throughout processors for serialization and deserialization

• libminifi/include/io/tls

1. 1. TLS classes. Exists in a separate directory so we can exclude OpenSSL for certain build directories.

• libminifi/include/processors

1. 1. Provides the processor implementations.

• libminifi/include/properties

1. 1. Configuration and properties related classes.

• libminifi/include/provenance

1. 1. Provenance related classes (provenance objects and repository)

• libminifi/include/utils

1. 1. Utility classes that are used throughout the code base

• libminifi/include/

1. 1. Contains the remainder of the classes that deal with scheduling, provenance, and the main object that controls the processing groups (FlowController)

Once you are familiar with the layout and have decided where to put your code, verified your tests pass, and the project builds, you can validate that your style matches the expectations of the project by running “make linter.” When code is committed test and the linter will be run in Travis CI, which will provide you a response via E-mail. If you only have one development environment, Travis CI will automatically run tests and the build within Linux and OSX, providing you confidence that your build works across platforms.

Make linter executes the linter against your project. If you are using Eclipse, you can use the Google Code Style Eclipse Formatter to reduce the number of artifacts generated during development [5].

Cross platform compatibility

Since MiNiFi C++ may run on a variety of platforms, please avoid known platform specific inclusions if possible. If you must make these inclusions, take care to use MACROS to avoid failure on platforms for which your code is non-portable.

Testing your changes

• For code changes, ensure that the full suite of tests is executed via make test within the build folder.  Please write or update unit tests to verify your changes.
• Did your change introduce new dependencies?  Are these dependencies licensed in a way that is compatible for inclusion under ASF 2.0?  Did you update the LICENSE file?
• For documentation related changes, ensure that format looks appropriate for the output in which it is rendered.

Performing the commit

In the interest of providing traceability, it is helpful to lead off your commit with the associated JIRA issue number (case-sensitive, MiNIFI in uppercase) and a summary of the change this commit is providing. Such an example is:

$ git commit -m " MiNIFI -XXX Ticket Summary Goes here."

The issue being listed first provides easy access to the supporting ticket and ensures it is not truncated from the varied means in which commits will be viewed.

[1] https://issues.apache.org/jira/browse/MINIFI/?selectedTab=com.atlassian.jira.jira-projects-plugin:issues-panel

[2] https://www.apache.org/foundation/glossary.html#ReviewThenCommit

[3] https://help.github.com/articles/about-pull-requests/

[4] https://cmake.org/cmake-tutorial/

[5] https://github.com/google/styleguide/blob/gh-pages/eclipse-cpp-google-style.xml