From a4f7af2f54e8f7dd5a8a92cf45996b4866f3f399 Mon Sep 17 00:00:00 2001 From: Oksana Salyk Date: Fri, 28 Jul 2023 13:55:46 +0200 Subject: [PATCH] common: split README.md file to README.md and INSTALL.md files --- INSTALL.md | 146 +++++++++++++++++++++++++++++++++ README.md | 209 ++++------------------------------------------- RELEASE_STEPS.md | 2 +- 3 files changed, 163 insertions(+), 194 deletions(-) create mode 100644 INSTALL.md diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000000..01170fd52be --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,146 @@ +# How to build the pmdk libraries from source + +## Dependencies + +Required packages for each supported OS are listed below. It is important to note that some tests and example applications require additional packages, but they do not interrupt building if they are missing. An appropriate message is displayed instead. For details please read the DEPENDENCIES section in the appropriate README file +(in [tests/](src/test/README) or [examples/](src/examples/README) sub-directories). + +See our **[Dockerfiles](utils/docker/images)** (used e.g. on our CI +systems) to get an idea what packages are required to build +the entire PMDK, with all the tests and examples. + +You will need to install the following required packages on the build system: + +* **autoconf** +* **pkg-config** +* **libndctl-devel** (v63 or later) +* **libdaxctl-devel** (v63 or later) +* **pandoc** (for documentation, required during install) + +The following packages are required only by selected PMDK components +or features: + +PMDK depends on libndctl to support RAS features. It is possible +to disable this support by passing `NDCTL_ENABLE=n` to `make`, but we strongly +discourage users from doing that. Disabling NDCTL strips PMDK from ability to +detect hardware failures, which may lead to silent data corruption. +For information how to disable RAS at runtime for kernels prior to 5.0.4 please +see https://github.com/pmem/pmdk/issues/4207. + +## Building PMDK + +To build from source, clone this tree: + +```sh +git clone https://github.com/pmem/pmdk +cd pmdk +``` + +For a stable version, checkout a [release tag](https://github.com/pmem/pmdk/releases) as follows. Otherwise skip this step to build the latest development release. + +```sh +git checkout tags/1.13.1 +``` + +Once all required [dependencies](#dependencies) are installed, PMDK is built using the + +```sh +make +``` + +By default, all code is built with the `-Werror` flag, which fails +the whole build when the compiler emits any warning. This is very useful during +development, but can be annoying in deployment. If you want to disable `-Werror`, +use the `EXTRA_CFLAGS` variable: + +```sh +make EXTRA_CFLAGS="-Wno-error" +``` + +>or + +```sh +make EXTRA_CFLAGS="-Wno-error=$(type-of-warning)" +``` + +## Installing PMDK + +After compiling the libraries, you can install them: + +```sh +sudo make install +``` + +## Testing PMDK + +You will need to install the following package to run unit tests: +* **ndctl** + +Before running the tests, you may need to prepare a test configuration file (`src/test/testconfig.sh`). Please see the available configuration settings in the example file [src/test/testconfig.sh.example](src/test/testconfig.sh.example). + +To build and run the **unit tests**: + +```sh +make check +``` + +To run a specific **subset of tests**, run for example: + +```sh +make check TEST_TYPE=short TEST_BUILD=debug TEST_FS=pmem +``` + +To **modify the timeout** which is available for **check** type tests, run: + +```sh +make check TEST_TIME=1m +``` + +This will set the timeout to 1 minute. + +Please refer to the [src/test/README](src/test/README) for more details on how to +run different types of tests. + +## Additional options + +Both building and installation scripts are very flexible. To see additional options please see the [Makefile](Makefile) file. + +### Memory Management Tools + +The PMDK libraries support standard Valgrind DRD, Helgrind and Memcheck, as well as a PM-aware version of [Valgrind](https://github.com/pmem/valgrind). +By default, support for all tools is enabled. If you wish to disable it, supply the compiler with `VG_\_ENABLED` flag set to 0, for example: + +```sh +make EXTRA_CFLAGS=-DVG_MEMCHECK_ENABLED=0 +``` + +`VALGRIND_ENABLED` flag, when set to 0, disables all Valgrind tools +(drd, helgrind, memcheck and pmemcheck). + +The `SANITIZE` flag allows the libraries to be tested with various +sanitizers. For example, to test the libraries with AddressSanitizer +and UndefinedBehaviorSanitizer, run: + +```sh +make SANITIZE=address,undefined clobber check +``` + +## Debugging + +To enable logging of debug information, use debug version of a library and set +desired log level using (library-specific) variable, e.g. `PMEM_LOG_LEVEL=`. + +For more details see appropriate manpage (debbuging section), e.g. +[libpmem(7)](https://pmem.io/pmdk/manpages/linux/master/libpmem/libpmem.7/#debugging-and-error-handling). + +## Experimental Packages + +Some components in the source tree are treated as experimental. By default, +those components are built but not installed (and thus not included in +packages). + +If you want to build/install experimental packages run: + +```sh +make EXPERIMENTAL=y [install,rpm,dpkg] +``` diff --git a/README.md b/README.md index 86bdad5fbf4..e05b4a6672c 100644 --- a/README.md +++ b/README.md @@ -18,17 +18,12 @@ Bugs and feature requests for this repo are tracked in our [GitHub Issues Databa 1. [Libraries and Utilities](#libraries-and-utilities) 2. [Getting Started](#getting-started) 3. [Version Conventions](#version-conventions) -4. [Dependencies](#dependencies) -5. [Building PMDK](#building-pmdk) - * [Make Options](#make-options) - * [Testing the Libraries](#testing-the-libraries) - * [Memory Management Tools](#memory-management-tools) -6. [Debugging](#debugging) -7. [Experimental Packages](#experimental-packages) +4. [Building and installing](#building-and-installing) +5. [Experimental Supports](#experimental-supports) * [Experimental Support for 64-bit ARM](#experimental-support-for-64-bit-arm-and-risc-v) * [Experimental Support for PowerPC](#experimental-support-for-powerpc) -8. [Archived and deprecated libraries](#archived-and-deprecated-libraries) -9. [Contact Us](#contact-us) +6. [Archived and deprecated libraries](#archived-and-deprecated-libraries) +7. [Contact Us](#contact-us) ## Libraries and Utilities @@ -67,195 +62,23 @@ Additionally, we recommend reading [Introduction to Programming with Persistent - **Release Candidates** have a '-rc{version}' tag, e.g. `0.2-rc3`, meaning _Release Candidate 3 for version 0.2_ - **Stable Releases** use a _major.minor_ tag like `0.2` -## Dependencies +## Building and installing -Required packages for each supported OS are listed below. It is important to note that some tests and example applications require additional packages, but they do not interrupt building if they are missing. An appropriate message is displayed instead. For details please read the DEPENDENCIES section in the appropriate README file -(in tests/ or examples/ sub-directories). +Install a few [dependencies](INSTALL.md#dependencies) and then build and install PMDK in the system. -See our **[Dockerfiles](utils/docker/images)** (used e.g. on our CI -systems) to get an idea what packages are required to build -the entire PMDK, with all the tests and examples. - -You will need to install the following required packages on the build system: - -* **autoconf** -* **pkg-config** -* **libndctl-devel** (v63 or later) -* **libdaxctl-devel** (v63 or later) -* **pandoc** (for documentation, required during install) - -The following packages are required only by selected PMDK components -or features: - -PMDK depends on libndctl to support RAS features. It is possible -to disable this support by passing NDCTL_ENABLE=n to "make", but we strongly -discourage users from doing that. Disabling NDCTL strips PMDK from ability to -detect hardware failures, which may lead to silent data corruption. -For information how to disable RAS at runtime for kernels prior to 5.0.4 please -see https://github.com/pmem/pmdk/issues/4207. - -## Building PMDK - -To build from source, clone this tree: -``` - $ git clone https://github.com/pmem/pmdk - $ cd pmdk -``` - -For a stable version, checkout a [release tag](https://github.com/pmem/pmdk/releases) as follows. Otherwise skip this step to build the latest development release. -``` - $ git checkout tags/1.13.1 -``` - -Once the build system is setup, the Persistent Memory Development Kit is built using the `make` command at the top level: -``` - $ make -``` - -By default, all code is built with the `-Werror` flag, which fails -the whole build when the compiler emits any warning. This is very useful during -development, but can be annoying in deployment. If you want to **disable -Werror**, -use the EXTRA_CFLAGS variable: -``` - $ make EXTRA_CFLAGS="-Wno-error" -``` ->or -``` - $ make EXTRA_CFLAGS="-Wno-error=$(type-of-warning)" -``` - -### Make Options - -There are many options that follow `make`. If you want to invoke make with the same variables multiple times, you can create a user.mk file in the top level directory and put all variables there. -For example: -``` - $ cat user.mk - EXTRA_CFLAGS_RELEASE = -ggdb -fno-omit-frame-pointer - PATH += :$HOME/valgrind/bin -``` -This feature is intended to be used only by developers and it may not work for all variables. Please do not file bug reports about it. Just fix it and make a PR. - -**Built-in tests:** can be compiled and ran with different compiler. To do this, you must provide the `CC` and `CXX` variables. These variables are independent and setting `CC=clang` does not set `CXX=clang++`. -For example: -``` - $ make CC=clang CXX=clang++ -``` -Once make completes, all the libraries and examples are built. You can play with the library within the build tree, or install it locally on your machine. For information about running different types of tests, please refer to the [src/test/README](src/test/README). - -**Installing the library** is convenient since it installs man pages and libraries in the standard system locations: -``` - (as root...) - # make install -``` - -To install this library into **other locations**, you can use the `prefix` variable, e.g.: +```sh +# get the source code +git clone https://github.com/pmem/pmdk +cd pmdk +# build +make -j +# install (optionally) +sudo make install ``` - $ make install prefix=/usr/local -``` -This will install files to /usr/local/lib, /usr/local/include /usr/local/share/man. - -**Prepare library for packaging** can be done using the DESTDIR variable, e.g.: -``` - $ make install DESTDIR=/tmp -``` -This will install files to /tmp/usr/lib, /tmp/usr/include /tmp/usr/share/man. - -**Man pages** (groff files) are generated as part of the `install` rule. To generate the documentation separately, run: -``` - $ make doc -``` -This call requires the following dependencies: **pandoc**. -**Install copy of source tree** can be done by specifying the path where you want it installed. -``` - $ make source DESTDIR=some_path -``` -For this example, it will be installed at $(DESTDIR)/pmdk. +If experience any issues or looking for additional options, check out the [INSTALL.md](INSTALL.md) file or [contact us](#contact-us). -**Build rpm packages** on rpm-based distributions is done by: -``` - $ make rpm -``` - -To build rpm packages without running tests: -``` - $ make BUILD_PACKAGE_CHECK=n rpm -``` -This requires **rpmbuild** to be installed. - -**Build dpkg packages** on Debian-based distributions is done by: -``` - $ make dpkg -``` - -To build dpkg packages without running tests: -``` - $ make BUILD_PACKAGE_CHECK=n dpkg -``` -This requires **devscripts** to be installed. - -### Testing the Libraries - -You will need to install the following package to run unit tests: -* **ndctl** - -Before running the tests, you may need to prepare a test configuration file (src/test/testconfig.sh). Please see the available configuration settings in the example file [src/test/testconfig.sh.example](src/test/testconfig.sh.example). - -To build and run the **unit tests**: -``` - $ make check -``` - -To run a specific **subset of tests**, run for example: -``` - $ make check TEST_TYPE=short TEST_BUILD=debug TEST_FS=pmem -``` - -To **modify the timeout** which is available for **check** type tests, run: -``` - $ make check TEST_TIME=1m -``` -This will set the timeout to 1 minute. - -Please refer to the **src/test/README** for more details on how to -run different types of tests. - -### Memory Management Tools - -The PMDK libraries support standard Valgrind DRD, Helgrind and Memcheck, as well as a PM-aware version of [Valgrind](https://github.com/pmem/valgrind). -By default, support for all tools is enabled. If you wish to disable it, supply the compiler with **VG_\_ENABLED** flag set to 0, for example: -``` - $ make EXTRA_CFLAGS=-DVG_MEMCHECK_ENABLED=0 -``` - -**VALGRIND_ENABLED** flag, when set to 0, disables all Valgrind tools -(drd, helgrind, memcheck and pmemcheck). - -The **SANITIZE** flag allows the libraries to be tested with various -sanitizers. For example, to test the libraries with AddressSanitizer -and UndefinedBehaviorSanitizer, run: -``` - $ make SANITIZE=address,undefined clobber check -``` - -## Debugging - -To enable logging of debug information, use debug version of a library and set -desired log level using (library-specific) variable, e.g. `PMEM_LOG_LEVEL=`. - -For more details see appropriate manpage (debbuging section), e.g. -[libpmem(7)](https://pmem.io/pmdk/manpages/linux/master/libpmem/libpmem.7.html#debugging-and-error-handling). - -## Experimental Packages - -Some components in the source tree are treated as experimental. By default, -those components are built but not installed (and thus not included in -packages). - -If you want to build/install experimental packages run: -``` - $ make EXPERIMENTAL=y [install,rpm,dpkg] -``` +## Experimental Supports ### Experimental Support for 64-bit ARM and RISC-V diff --git a/RELEASE_STEPS.md b/RELEASE_STEPS.md index 448c1f1cbd2..37948162262 100644 --- a/RELEASE_STEPS.md +++ b/RELEASE_STEPS.md @@ -29,7 +29,7 @@ After that you'd also have to add this new key to your GitHub account - please d To do a release: - add an entry to ChangeLog, remember to change the day of the week in the release date - for major releases mention compatibility with the previous release, if needed -- update reference to stable release in README.md (update line `git checkout tags/$VERSION-1` to the new release $VERSION) +- update reference to stable release in [INSTALL.md](INSTALL.md) (update line `git checkout tags/$VERSION-1` to the new release $VERSION) - omit this step for an rc version ```bash