arpadboda commented on a change in pull request #661: MINIFICPP-1022 - Refactored third party build system URL: https://github.com/apache/nifi-minifi-cpp/pull/661#discussion_r349580096
########## File path: ThirdParties.md ########## @@ -0,0 +1,393 @@ +<!-- + 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 + http://www.apache.org/licenses/LICENSE-2.0 + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +--> +# Apache MiNiFi C++ Third Parties guide + +Apache MiNiFi C++ uses many third party libraries, both for core functionality and for extensions. + +This document describes the way we build and use third parties and provides a guide for adding new ones. + +## Table of Contents + + * [Table of Contents](#table-of-contents) + * [Choosing a third party](#choosing-a-third-party) + + [License](#license) + * [Built-in or system dependency](#built-in-or-system-dependency) + * [System dependency](#system-dependency) + + [bootstrap.sh](#bootstrapsh) + + [Find\<Package\>.cmake](#find--package--cmake) + + [find_package](#find-package) + * [Built-in dependency](#built-in-dependency) + + [ExternalProject_Add](#externalproject-add) + - [`URL` and `GIT`](#-url--and--git-) + - [`SOURCE_DIR`](#-source-dir-) + - [`PATCH_COMMAND`](#-patch-command-) + - [`CMAKE_ARGS`](#-cmake-args-) + - [`BUILD_BYPRODUCTS`](#-build-byproducts-) + - [`EXCLUDE_FROM_ALL`](#-exclude-from-all-) + - [`LIST_SEPARATOR`](#-list-separator-) + + [Choosing a source](#choosing-a-source) + + [Patching](#patching) + + [Build options](#build-options) + + [find_package-like variables](#find-package-like-variables) + + [Imported library targets](#imported-library-targets) + + [Using third parties in other third parties](#using-third-parties-in-other-third-parties) + - [Making a third party available to other third parties](#making-a-third-party-available-to-other-third-parties) + * [Find\<Package\>.cmake](#find--package--cmake-1) + * [Passthrough variables](#passthrough-variables) + - [Using a third party from another third party](#using-a-third-party-from-another-third-party) + * [Dependencies](#dependencies) + * [CMake module path and passthrough args](#cmake-module-path-and-passthrough-args) + + [Interface libraries](#interface-libraries) + + +## Choosing a third party + +Deciding if a third party is needed for a particular task and if so, choosing between the different implementations is difficult. A few points that have to considered are: + - every third party introduces risk, both operational and security + - every third party adds a maintenance burden: it has to be tracked for issues, updated, adapted to changes in the build framework + - not using a third party and relying on less tested homegrown solutions however usually carry a greater risk than using one + - introducing a new third party dependency to the core should be done with the utmost care. If we make a third party a core dependency, it will increase build time, executable size and the burden to maintain API compatibility. + +A few tips to choose a third party: + - you have to choose a third party with a [proper license](#license) + - prefer well-maintained third parties. Abandoned projects will have a huge maintenance burden. + - prefer third parties with frequent/regular releases. There are some projects with a huge number of commits and a very long time since the last release, and we are at a disadvantage in determining whether the actual state of the master is stable: the maintainers should be the judges of that. + - prefer third parties with the smaller number of transitive dependencies. If the third party itself needs other third parties, that increases the work greatly to get it done properly at the first time and then maintain it afterwards. + +### License +Only third parties with an Apache License 2.0-compatible license may be linked with this software. + +To make sure the third party's license is compatible with Apache License 2.0, refer to the [ASF 3RD PARTY LICENSE POLICY +](https://www.apache.org/legal/resolved.html). Please also note that license compatibility is a one-way street: a license may be compatible with Apache License 2.0 but not the other way round. + +GPL and LGPL are generally not compatible. + +## Built-in or system dependency +When deciding whether a third party dependency should be provided by the system, or compiled and shipped by us, there are many factors to consider. + +| | Advantages | Disadvantages | +|----------|-------------------------------------------------------------------------------------|------------------------------------------------------------| +| System | Smaller executable size | Less control over third-party | +| | Faster compilation | Can't add patches | +| | | Has to be supported out-of-the box on all target platforms | +| | | Usually not available on Windows | +| Built-in | High level of control over third-party (consistent version and features everywhere) | Larger executable size | +| | Can add patches | Slower compilation | +| | Does not have to be supported by the system | | +| | Works on Windows | | + +Even if choosing a system dependency, a built-in version for Windows usually has to be made. + +Both a system and a built-in version can be supported, in which case the choice should be configurable via CMake options. + +**The goal is to abstract the nature of the third party from the rest of the project**, and create targets from them, that automatically take care of building or finding the third party and any dependencies, be it target, linking or include. + +## System dependency + +To add a new system dependency, you have to follow the following steps: + +### bootstrap.sh + +If you are using a system dependency, you have to ensure that the development packages are installed on the build system if the extension is selected. + +To ensure this, edit `bootstrap.sh` and all the platform-specific scripts (`centos.sh`, `fedora.sh`, `debian.sh`, `suse.sh`, `rheldistro.sh`, `darwin.sh`). + +### Find\<Package\>.cmake + +If a `Find<Package>.cmake` is provided for your third party by not unreasonably new (not later than 3.2) CMake versions out of the box, then you have nothing further to do, unless they don't create imported library targets. + +If it is not provided, you have three options + - if a newer CMake version provides it, you can try "backporting it" + - you can search for an already implemented one in other projects with an acceptable license + - if everything else fails, you can write one yourself + +If you don't end up writing it from scratch, make sure that you indicate the original source in the `NOTICE` file. Review comment: License is needed as well. ---------------------------------------------------------------- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. For queries about this service, please contact Infrastructure at: [email protected] With regards, Apache Git Services
