mdbx: update READMEs (build section).

Change-Id: I731737edc594f22f81cbfc080d857caeb31b9f9a

README-RU.md

@@ -1,39 +1,41 @@
-## The [repository now only mirrored on the Github](https://abf.io/erthink/libmdbx) due to illegal discriminatory restrictions for Russian Crimea and for sovereign crimeans.
+### The [repository now only mirrored on the Github](https://abf.io/erthink/libmdbx) due to illegal discriminatory restrictions for Russian Crimea and for sovereign crimeans.
 <!-- Required extensions: pymdownx.betterem, pymdownx.tilde, pymdownx.emoji, pymdownx.tasklist, pymdownx.superfences -->
----
+-----
 
 libmdbx
 ======================================
-**The revised and extended descendant of [Symas LMDB](https://symas.com/lmdb/).**
+Доработанный и расширенный потомок [Lightning Memory-Mapped Database](https://ru.bmstu.wiki/LMDB_(Lightning_Memory-Mapped_Database)) (aka _LMDB_).
+English version is [here](README.md).
+
+_libmdbx_ превосходит LMDB по возможностям и надежности, не уступая в
+производительности. _libmdbx_ работает на Linux, FreeBSD, MacOS X и
+других ОС соответствующих POSIX.1-2008, а также поддерживает Windows в
+качестве дополнительной платформы.
+
+Отдельно ведётся не-публичная разработка следующей версии, в которой
+будет кардинальное изменение как API, так и формата базы данных. Цель
+этой революции - обеспечение более четкого и надежного API, добавление
+новых функций, а также наделение базы данных новыми свойствами.
+
+*Всё будет хорошо. The Future will (be) [Positive](https://www.ptsecurity.ru).*
 
-*The Future will (be) Positive. Всё будет хорошо.*
 [![Build Status](https://travis-ci.org/leo-yuriev/libmdbx.svg?branch=master)](https://travis-ci.org/leo-yuriev/libmdbx)
 [![Build status](https://ci.appveyor.com/api/projects/status/ue94mlopn50dqiqg/branch/master?svg=true)](https://ci.appveyor.com/project/leo-yuriev/libmdbx/branch/master)
 [![Coverity Scan Status](https://scan.coverity.com/projects/12915/badge.svg)](https://scan.coverity.com/projects/reopen-libmdbx)
 
-English version of this README is [here](README.md), also the translations [by Google](https://translate.googleusercontent.com/translate_c?act=url&ie=UTF8&sl=ru&tl=en&u=https://github.com/leo-yuriev/libmdbx/tree/master)
-and [by Yandex](https://translate.yandex.ru/translate?url=https%3A%2F%2Fgithub.com%2FReOpen%2Flibmdbx%2Ftree%2Fmaster&lang=ru-en).
-
-### Статус проекта
-
-_libmdbx_ работает на Linux, FreeBSD, MacOS X и других ОС
-соответствующих POSIX.1-2008, а также поддерживает Windows (начиная с
-Windows XP) в качестве дополнительной платформы.
-
-Отдельно ведётся не-публичная разработка следующей версии, в которой
-будет большое изменение как API, так и формата базы данных. Цель этой
-революции - обеспечение более четкого и надежного API, добавление новых
-функций, а также наделение базы данных новыми свойствами.
-
 ## Содержание
 - [Обзор](#Обзор)
-  - [Сравнение с другими СУБД](#Сравнение-с-другими-СУБД)
+    - [Сравнение с другими базами данных](#Сравнение-с-другими-базами-данных)
-  - [История & Acknowledgments](#История)
+    - [История & Выражение признательности](#История)
-- [Основные свойства](#Основные-свойства)
+- [Описание](#Описание)
+    - [Ключевые свойства](#Ключевые-свойства)
     - [Доработки и усовершенствования относительно LMDB](#Доработки-и-усовершенствования-относительно-lmdb)
     - [Недостатки и Компромиссы](#Недостатки-и-Компромиссы)
         - [Проблема долгих чтений](#Проблема-долгих-чтений)
         - [Сохранность данных в режиме асинхронной фиксации](#Сохранность-данных-в-режиме-асинхронной-фиксации)
+- [Использование](#Использование)
+    - [Сборка](#Сборка)
+    - [Привязки к другим языкам](#Привязки-к-другим-языкам)
 - [Сравнение производительности](#Сравнение-производительности)
     - [Интегральная производительность](#Интегральная-производительность)
     - [Масштабируемость чтения](#Масштабируемость-чтения)
@@ -42,6 +44,7 @@ Windows XP) в качестве дополнительной платформы.
     - [Асинхронная фиксация](#Асинхронная-фиксация)
     - [Потребление ресурсов](#Потребление-ресурсов)
 
+-----
 
 ## Обзор
 _libmdbx_ - это встраиваемый key-value движок хранения со специфическим
@@ -75,7 +78,7 @@ _libmdbx_ не использует
 сценарии использования.
 
 
-### Сравнение с другими СУБД
+### Сравнение с другими базами данных
 
 На данный момент, пожалуйста, обратитесь к [главе "сравнение BoltDB с
 другими базами
@@ -101,16 +104,20 @@ Tables](https://github.com/leo-yuriev/libfpta), aka ["Позитивные
 Technologies](https://www.ptsecurity.ru).
 
 
-#### Выражение признательности
+### Выражение признательности
 
-Говард Чу (Howard Chu) <hyc@openldap.org> - автор движка LMDB, от
+Говард Чу (Howard Chu) <hyc@openldap.org> является автором движка LMDB, от
 которого в 2015 году произошел MDBX.
 
-Мартин Хеденфальк (Martin Hedenfalk) <martin@bzero.se> - автор кода
+Мартин Хеденфальк (Martin Hedenfalk) <martin@bzero.se> является автором кода
 `btree.c`, который использовался для начала разработки LMDB.
 
-Основные свойства
+-----
-=================
+
+Описание
+========
+
+## Ключевые свойства
 
 _libmdbx_ наследует все ключевые возможности и особенности своего
 прародителя
@@ -165,8 +172,7 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
 кэшированием. Всё необходимое штатно выполняет ядро ОС.
 
 
-Доработки и усовершенствования относительно LMDB
+## Доработки и усовершенствования относительно LMDB
-================================================
 
 1. Автоматическое динамическое управление размером БД согласно
 параметрам задаваемым функцией `mdbx_env_set_geometry()`, включая шаг
@@ -344,7 +350,6 @@ Amplification Factor) и RAF (Read Amplification Factor) также Olog(N).
 Поэтому _libmdbx_ может немного отставать в тестах производительность от
 LMDB, где используются именованные мьютексы.
 
---------------------------------------------------------------------------------
 
 ## Недостатки и Компромиссы
 
@@ -402,7 +407,7 @@ LMDB, где используются именованные мьютексы.
    > Подробности ниже.
 
 
-#### Проблема долгих чтений
+### Проблема долгих чтений
 *Следует отметить*, что проблема "сборки мусора" так или иначе
 существует во всех СУБД (Vacuum в PostgreSQL). Однако в случае _libmdbx_
 и LMDB она проявляется более остро, прежде всего из-за высокой
@@ -468,7 +473,7 @@ LMDB, где используются именованные мьютексы.
 за счет эффективной работы [BBWC](https://en.wikipedia.org/wiki/BBWC)
 при включении `LIFO RECLAIM` в _libmdbx_.
 
-#### Сохранность данных в режиме асинхронной фиксации
+### Сохранность данных в режиме асинхронной фиксации
 При работе в режиме `WRITEMAP+MAPSYNC` запись измененных страниц
 выполняется ядром ОС, что имеет ряд преимуществ. Так например, при крахе
 приложения, ядро ОС сохранит все изменения.
@@ -531,6 +536,118 @@ LMDB, где используются именованные мьютексы.
 
 --------------------------------------------------------------------------------
 
+Использование
+=============
+
+## Сборка
+
+Для сборки на всех платформах кроме Windows вам потребуются не-дремучие
+версии: GNU Make, [bash](https://ru.wikipedia.org/wiki/Bash), компиляторы C и C++ совместимые с GCC или CLANG.
+
+Исторически сборка _libmdbx_ основывается на одном
+[Makefile](https://ru.wikipedia.org/wiki/Makefile), что предполагает
+разные рецепты сборки в зависимости от целевой платформы. В следующих
+версиях планируется переход на использование
+[CMake](https://ru.wikipedia.org/wiki/CMake), с отказом от поддержки
+других инструментов.
+
+#### Выгрузка DSO/DLL и деструкторы Thread-Local-Storage объектов
+При сборке _libmdbx_ в виде разделяемой библиотеки, либо использовании
+статической _libmdbx_ в составе другой динамической библиотеке,
+желательно убедиться, что ваша система обеспечивает корректность вызова
+деструкторов Thread-Local-Storage объектов при выгрузке динамических
+библиотек.
+
+Если это не так, то при выгрузке динамической библиотеки с _libmdbx_
+внутри возможна либо утечка ресурсов, либо падения из-за вызова
+деструкторов из уже выгруженного DSO/DLL объекта. Проблема может
+проявляться только в многопоточном приложении, которое производит
+выгрузку разделяемых динамических библиотек с кодом _libmdbx_ внутри,
+после использования _libmdbx_. Заведомо известно, что TLS-деструкторы
+корректно обслуживаются:
+
+- На всех актуальных версиях Windows (Windows 7 и последующих).
+
+- На системах c функцией
+[`__cxa_thread_atexit_impl()`](https://sourceware.org/glibc/wiki/Destructor%20support%20for%20thread_local%20variables)
+в стандартной библиотеке C. В том числе на системах с GNU libc версии
+2.18 и выше.
+
+- На системах с libpthread/ntpl из состава GNU libc с исправлением
+ошибок [#21031](https://sourceware.org/bugzilla/show_bug.cgi?id=21031) и
+[#21032](https://sourceware.org/bugzilla/show_bug.cgi?id=21032), либо
+где нет подобных ошибок в реализации pthreads.
+
+### Linux и другие платформы с GNU Make
+Для сборки библиотеки достаточно выполнить `make all` в директории с
+исходными текстами, а для выполнения базовых тестов `make check`.
+
+Если установленный в система `make` не является GNU Make, то при попытке
+сборки будет масса ошибок от make. В этом случае, возможно, вместо
+`make` вам следует использовать `gmake`, либо даже `gnu-make` и т.п.
+
+### FreeBSD и родственные платформы
+Как правило, на таких системах по-умолчанию используется Berkeley Make.
+А GNU Make вызывается командой `gmake` или может отсутствовать. Кроме
+этого может отсутствовать [`bash`](https://ru.wikipedia.org/wiki/Bash).
+
+Вам необходимо установить требуемые компоненты: GNU Make, bash,
+компиляторы C и C++ совместимые с GCC или CLANG. После этого для сборки
+библиотеки достаточно выполнить `gmake all` (или `make all`) в
+директории с исходными текстами, а для выполнения базовых тестов `gmake
+check` (или `make check`).
+
+### Windows
+Для сборки libmdbx_ для ОС Windows рекомендуется использовать [Microsoft
+Visual Studio](https://ru.wikipedia.org/wiki/Microsoft_Visual_Studio),
+но не такие инструменты как MinGW, MSYS или Cygwin. Для этого в набор
+исходных кодов _libmdbx_ входят соответствующие файлы проектов
+совместимые с Visual Studio 2015, Windows SDK для Windows 8.1 и более
+поздними версиями. Достаточно открыть `mdbx.sln` и выполнить сборку
+библиотеки.
+
+Для сборки с более новыми версиями SDK или Visual Studio должно быть
+достаточно выполнить "Retarget solution". Для сборки под старые версии
+Windows (например Windows XP) или более старыми компиляторами вам
+потребуется самостоятельно преобразовать или воссоздать файлы проектов.
+
+Сборка посредством MinGW, MSYS или Cygwin потенциально возможна. Однако,
+эти сценарии не тестируются и вероятно потребуют от вас доработки
+`Makefile`. Следует отметить, что в _libmdbx_ предприняты усилия для
+устранения runtime зависимостей от CRT и других библиотек Visual Studio.
+
+Пример запуска базового сценария тестирования можно найти в
+[CI-сценарии](appveyor.yml) для [AppVeyor](https://www.appveyor.com/).
+Для выполнения [сценария длительного стохастического
+тестирования](test/long_stochastic.sh) потребуется
+[`bash`](https://ru.wikipedia.org/wiki/Bash), а само тестирование
+рекомендуется выполнять с размещением тестовых данных на
+[RAM-диске](https://ru.wikipedia.org/wiki/RAM-%D0%B4%D0%B8%D1%81%D0%BA).
+
+### MacOS X
+Актуальные [нативные сборочные
+инструменты](https://ru.wikipedia.org/wiki/Xcode) для MacOS X включают
+GNU Make, CLANG и устаревшую версию bash. Поэтому для сборки библиотеки
+достаточно выполнить `make all` в директории с исходными текстами, а для
+выполнения базовых тестов `make check`. Если же что-то пойдет не так, то
+рекомендуется установить [Homebrew](https://brew.sh/) и попробовать ещё
+раз.
+
+Для выполнения [сценария длительного стохастического
+тестирования](test/long_stochastic.sh) потребуется установка актуальной
+(не устаревшей) версии [`bash`](https://ru.wikipedia.org/wiki/Bash). Для
+этого рекомендуется установить [Homebrew](https://brew.sh/), а затем
+выполнить `brew install bash`.
+
+## Привязки к другим языкам
+
+  | Runtime  | GitHub | Author |
+  | -------- | ------ | ------ |
+  | Java     | [mdbxjni](https://github.com/castortech/mdbxjni)   | [Castor Technologies](https://castortech.com/) |
+  | .NET     | [mdbx.NET](https://github.com/wangjia184/mdbx.NET) | [Jerry Wang](https://github.com/wangjia184) |
+
+--------------------------------------------------------------------------------
+
 Сравнение производительности
 ============================
 
@@ -542,9 +659,8 @@ SAMSUNG MZNTD512HAGL-000L1 (DXT23L0Q) 512 Гб.
 сценарии тестирования [доступны на
 github](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015).
 
---------------------------------------------------------------------------------
 
-### Интегральная производительность
+## Интегральная производительность
 
 Показана соотнесенная сумма ключевых показателей производительности в трёх
 бенчмарках:
@@ -571,7 +687,7 @@ github](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015).
 
 --------------------------------------------------------------------------------
 
-### Масштабируемость чтения
+## Масштабируемость чтения
 
 Для каждого движка показана суммарная производительность при
 одновременном выполнении запросов чтения/поиска в 1-2-4-8 потоков на
@@ -581,7 +697,7 @@ github](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015).
 
 --------------------------------------------------------------------------------
 
-### Синхронная фиксация
+## Синхронная фиксация
 
  - Линейная шкала слева и темные прямоугольники соответствуют количеству
    транзакций в секунду, усредненному за всё время теста.
@@ -607,7 +723,7 @@ github](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015).
 
 --------------------------------------------------------------------------------
 
-### Отложенная фиксация
+## Отложенная фиксация
 
  - Линейная шкала слева и темные прямоугольники соответствуют количеству
    транзакций в секунду, усредненному за всё время теста.
@@ -638,7 +754,7 @@ _libmdbx_ при этом не ведет WAL, а передает весь ко
 
 --------------------------------------------------------------------------------
 
-### Асинхронная фиксация
+## Асинхронная фиксация
 
  - Линейная шкала слева и темные прямоугольники соответствуют количеству
    транзакций в секунду, усредненному за всё время теста.
@@ -668,7 +784,7 @@ _libmdbx_ при этом не ведет WAL, а передает весь ко
 
 --------------------------------------------------------------------------------
 
-### Потребление ресурсов
+## Потребление ресурсов
 
 Показана соотнесенная сумма использованных ресурсов в ходе бенчмарка в
 режиме отложенной фиксации:

README.md

@@ -1,47 +1,41 @@
-## The [repository now only mirrored on the Github](https://abf.io/erthink/libmdbx) due to illegal discriminatory restrictions for Russian Crimea and for sovereign crimeans.
+### The [repository now only mirrored on the Github](https://abf.io/erthink/libmdbx) due to illegal discriminatory restrictions for Russian Crimea and for sovereign crimeans.
 <!-- Required extensions: pymdownx.betterem, pymdownx.tilde, pymdownx.emoji, pymdownx.tasklist, pymdownx.superfences -->
----
+-----
 
 libmdbx
 ======================================
-**Revised and extended descendant of [Symas LMDB](https://symas.com/lmdb/).**
+Revised and extended descendant of [Lightning Memory-Mapped Database](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database) (aka _LMDB_).
+Русскоязычная версия [здесь](README-RU.md).
+
+_libmdbx_ is superior to LMDB in terms of features and reliability, not
+inferior in performance. _libmdbx_ works on Linux, FreeBSD, MacOS X and
+other systems compliant with POSIX.1-2008, but also support Windows as a
+complementary platform.
+
+The next version is under active non-public development, which will
+radically change both the API and the database format. The goal of this
+revolution is to provide a clearer and more reliable API, add more
+features and new database properties.
+
+*The Future will (be) [Positive](https://www.ptsecurity.com). Всё будет хорошо.*
 
-*The Future will (be) positive.*
 [![Build Status](https://travis-ci.org/leo-yuriev/libmdbx.svg?branch=master)](https://travis-ci.org/leo-yuriev/libmdbx)
 [![Build status](https://ci.appveyor.com/api/projects/status/ue94mlopn50dqiqg/branch/master?svg=true)](https://ci.appveyor.com/project/leo-yuriev/libmdbx/branch/master)
 [![Coverity Scan Status](https://scan.coverity.com/projects/12915/badge.svg)](https://scan.coverity.com/projects/reopen-libmdbx)
 
-Русскоязычная версия этого README [здесь](README-RU.md).
+## Table of Contents
-
-## Project Status
-
-_libmdbx_ works on Linux, FreeBSD, MacOS X and other systems compliant
-with POSIX.1-2008, but also support Windows as a complementary platform.
-
-The next version
-([_devel_](https://github.com/leo-yuriev/libmdbx/tree/devel) branch) is
-under active non-public development, i.e. API and set of features are
-volatile. The goal of this revolution is to provide a clearer and more
-reliable API, adding set of features and a new database properties.
-
-Don't miss libmdbx for other runtimes:
-
-  | Runtime  | GitHub | Author |
-  | ------------- | ------------- | ------------- |
-  | Java  | [mdbxjni](https://github.com/castortech/mdbxjni)   | [Castor Technologies](https://castortech.com/) |
-  | .NET  | [mdbx.NET](https://github.com/wangjia184/mdbx.NET) | [Jerry Wang](https://github.com/wangjia184) |
-
------
-
-## Contents
 - [Overview](#overview)
-  - [Comparison with other DBs](#comparison-with-other-dbs)
+    - [Comparison with other databases](#comparison-with-other-databases)
     - [History & Acknowledgments](#history)
-- [Main features](#main-features)
+- [Description](#description)
+    - [Key features](#key-features)
     - [Improvements over LMDB](#improvements-over-lmdb)
     - [Gotchas](#gotchas)
         - [Problem of long-time reading](#problem-of-long-time-reading)
         - [Durability in asynchronous writing mode](#durability-in-asynchronous-writing-mode)
+- [Usage](#usage)
+    - [Building](#building)
+    - [Bindings](#bindings)
 - [Performance comparison](#performance-comparison)
     - [Integral performance](#integral-performance)
     - [Read scalability](#read-scalability)
@@ -50,6 +44,7 @@ Don't miss libmdbx for other runtimes:
     - [Async-write mode](#async-write-mode)
     - [Cost comparison](#cost-comparison)
 
+-----
 
 ## Overview
 _libmdbx_ is an embedded lightweight key-value database engine oriented
@@ -76,7 +71,7 @@ _libmdbx_ uses [B+Trees](https://en.wikipedia.org/wiki/B%2B_tree) and
 doesn't use [WAL](https://en.wikipedia.org/wiki/Write-ahead_logging)
 which might be a caveat for some workloads.
 
-### Comparison with other DBs
+### Comparison with other databases
 For now please refer to [chapter of "BoltDB comparison with other
 databases"](https://github.com/coreos/bbolt#comparison-with-other-databases)
 which is also (mostly) applicable to MDBX.
@@ -93,16 +88,19 @@ conference](http://www.highload.ru/2015/abstracts/1831.html).
 Since early 2017 _libmdbx_ is used in [Fast Positive Tables](https://github.com/leo-yuriev/libfpta),
 and development is funded by [Positive Technologies](https://www.ptsecurity.com).
 
-#### Acknowledgments
+### Acknowledgments
-Howard Chu <hyc@openldap.org> - the author of LMDB, from which
+Howard Chu <hyc@openldap.org> is the author of LMDB, from which
 originated the MDBX in 2015.
 
-Martin Hedenfalk <martin@bzero.se> - the author of `btree.c` code, which
+Martin Hedenfalk <martin@bzero.se> is the author of `btree.c` code, which
 was used for begin development of LMDB.
 
+-----
 
-Main features
+Description
-=============
+===========
+
+## Key features
 
 _libmdbx_ inherits all features and characteristics from
 [LMDB](https://en.wikipedia.org/wiki/Lightning_Memory-Mapped_Database):
@@ -147,10 +145,8 @@ without freezing writers.
 
 9. No additional memory management, all done by basic OS services.
 
---------------------------------------------------------------------------------
 
-Improvements over LMDB
+## Improvements over LMDB
-======================
 
 1. Automatic dynamic DB size management according to the parameters
 specified by `mdbx_env_set_geometry()` function. Including
@@ -308,7 +304,6 @@ against incompetent user actions (aka
 _libmdbx_ may be a little lag in performance tests from LMDB where a
 named mutexes are used.
 
---------------------------------------------------------------------------------
 
 ## Gotchas
 
@@ -357,7 +352,7 @@ of data.
   > Details below.
 
 
-#### Problem of long-time reading
+### Problem of long-time reading
 Garbage collection problem exists in all databases one way or another
 (e.g. VACUUM in PostgreSQL). But in _libmdbx_ and LMDB it's even more
 discernible because of high transaction rate and intentional internals
@@ -384,7 +379,7 @@ writing data to persistent storage.
 operations and the `LIFO RECLAIM` mode which addresses performance
 degradation.
 
-#### Durability in asynchronous writing mode
+### Durability in asynchronous writing mode
 In `WRITEMAP+MAPSYNC` mode updated (aka dirty) pages are written to
 persistent storage by the OS kernel. This means that if the application
 fails, the OS kernel will finish writing all updated data to disk and
@@ -434,6 +429,119 @@ after a system crash, i.e. like the LMDB.
 Next version of _libmdbx_ will be automatically create steady commit
 points in async-write mode upon completion transfer data to the disk.
 
+--------------------------------------------------------------------------------
+
+Usage
+=====
+
+## Building
+
+To build on all platforms except Windows the prerequirements are the
+same: non-obsolete versions of GNU Make,
+[bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)), C and C++
+compilers compatible with GCC or CLANG. On Windows you will need only :
+Microsoft Visual Studio 2015 or later, Windows SDK for Windows 8 or
+later.
+
+Historically, the libmdbx builing is based on single
+[Makefile](https://en.wikipedia.org/wiki/Makefile) which assumes
+different recipes depending on target platform. In the next versions, it
+is planned to switch to [CMake](https://en.wikipedia.org/wiki/CMake),
+with the refusal to support other tools.
+
+#### DSO/DLL unloading and destructors of Thread-Local-Storage objects
+When building _libmdbx_ as a shared library or use static _libmdbx_ as a
+part of another dynamic library, it is advisable to make sure that your
+system ensures the correctness of the call destructors of
+Thread-Local-Storage objects when unloading dynamic libraries'.
+
+If this is not the case, then unloading a dynamic-link library with
+_libmdbx_ code inside, can result in either a resource leak or a crash
+due to calling destructors from an already unloaded DSO/DLL object. The
+problem can only manifest in a multithreaded application, which makes
+the unloading of shared dynamic libraries with _libmdbx_ code inside,
+after using _libmdbx_. It is known that TLS-destructors are properly
+maintained in the following cases:
+
+- On all modern versions of Windows (Windows 7 and later).
+
+- On systems with the
+[`__cxa_thread_atexit_impl()`](https://sourceware.org/glibc/wiki/Destructor%20support%20for%20thread_local%20variables)
+function in the standard C library, including systems with GNU libc
+version 2.18 and later.
+
+- On systems with libpthread/ntpl from GNU libc with bug fixes
+[#21031](https://sourceware.org/bugzilla/show_bug.cgi?id=21031) and
+[#21032](https://sourceware.org/bugzilla/show_bug.cgi?id=21032), or
+where there are no similar bugs in the pthreads implementation.
+
+### Linux and other platforms with GNU Make
+To build the library it is enough to execute `make all` in the directory
+of source code, and `make check` for execute the basic tests.
+
+If the `make` installed on the system is not GNU Make, there will be a
+lot of errors from make when trying to build. In this case, perhaps you
+should use `gmake` instead of `make`, or even `gnu-make`, etc.
+
+### FreeBSD and related platforms
+As a rule, in such systems, the default is to use Berkeley Make. And GNU
+Make is called by the gmake command or may be missing. In addition,
+[bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)) may be absent.
+
+You need to install the required components: GNU Make, bash, C and C++
+compilers compatible with GCC or CLANG. After that, to build the
+library, it is enough execute `gmake all` (or `make all`) in the
+directory with source code, and `gmake check` (or `make check`) to run
+the basic tests.
+
+### Windows
+For building _libmdbx_ on Windows the [Microsoft Visual
+Studio](https://en.wikipedia.org/wiki/Microsoft_Visual_Studio) is
+recommended, but not tools such as MinGW, MSYS, or Cygwin. To do this,
+the libmdbx source code includes the set of appropriate project files
+that are compatible with Visual Studio 2015, the Windows SDK for Windows
+8.1, and later. Just open `mdbx.sln` in Visual Studio and build the
+library.
+
+To build with newer versions of the SDK or Visual Studio, it should be
+sufficient to execute "Retarget solution". To build for older versions
+of Windows (such as Windows XP) or by older compilers, you will need to
+convert or recreate the corresponding project files yourself.
+
+Building by MinGW, MSYS or Cygwin is potentially possible. However,
+these scripts are not tested and will probably require you to modify the
+Makefile. It should be noted that in _libmdbx_ was efforts to resolve
+runtime dependencies from CRT and other libraries Visual Studio.
+
+An example of running a basic test script can be found in the
+[CI-script](appveyor.yml) for [AppVeyor](https://www.appveyor.com/). To
+run the [long stochastic test scenario](test/long_stochastic.sh),
+[bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)) is required, and
+the such testing is recommended with place the test data on the
+[RAM-disk](https://en.wikipedia.org/wiki/RAM_drive).
+
+### MacOS X
+Current [native build tools](https://en.wikipedia.org/wiki/Xcode) for
+MacOS X include GNU Make, CLANG and an outdated version of bash.
+Therefore, to build the library, it is enough to run `make all` in the
+directory with source code, and run `make check` to execute the base
+tests. If something goes wrong, it is recommended to install
+[Homebrew](https://brew.sh/) and try again.
+
+To run the [long stochastic test scenario](test/long_stochastic.sh), you
+will need to install the current (not outdated) version of
+[bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)). To do this, we
+recommend that you install [Homebrew](https://brew.sh/) and then execute
+`brew install bash`.
+
+## Bindings
+
+  | Runtime  | GitHub | Author |
+  | -------- | ------ | ------ |
+  | Java     | [mdbxjni](https://github.com/castortech/mdbxjni)   | [Castor Technologies](https://castortech.com/) |
+  | .NET     | [mdbx.NET](https://github.com/wangjia184/mdbx.NET) | [Jerry Wang](https://github.com/wangjia184) |
+
+
 --------------------------------------------------------------------------------
 
 Performance comparison
@@ -444,9 +552,7 @@ and multiple [scripts](https://github.com/pmwkaa/ioarena/tree/HL%2B%2B2015)
 runs on Lenovo Carbon-2 laptop, i7-4600U 2.1 GHz, 8 Gb RAM,
 SSD SAMSUNG MZNTD512HAGL-000L1 (DXT23L0Q) 512 Gb.
 
---------------------------------------------------------------------------------
+## Integral performance
-
-### Integral performance
 
 Here showed sum of performance metrics in 3 benchmarks:
 
@@ -472,7 +578,7 @@ Here showed sum of performance metrics in 3 benchmarks:
 
 --------------------------------------------------------------------------------
 
-### Read Scalability
+## Read Scalability
 
 Summary performance with concurrent read/search queries in 1-2-4-8
 threads on 4 CPU cores machine.
@@ -481,7 +587,7 @@ threads on 4 CPU cores machine.
 
 --------------------------------------------------------------------------------
 
-### Sync-write mode
+## Sync-write mode
 
  - Linear scale on left and dark rectangles mean arithmetic mean
  transactions per second;
@@ -503,7 +609,7 @@ and after full run the database contains 10,000 small key-value records.
 
 --------------------------------------------------------------------------------
 
-### Lazy-write mode
+## Lazy-write mode
 
  - Linear scale on left and dark rectangles mean arithmetic mean of
  thousands transactions per second;
@@ -530,7 +636,7 @@ records.
 
 --------------------------------------------------------------------------------
 
-### Async-write mode
+## Async-write mode
 
  - Linear scale on left and dark rectangles mean arithmetic mean of
  thousands transactions per second;
@@ -554,7 +660,7 @@ and after full run the database contains 10,000 small key-value records.
 
 --------------------------------------------------------------------------------
 
-### Cost comparison
+## Cost comparison
 
 Summary of used resources during lazy-write mode benchmarks: