ext/libuv/README.md in libuv-3.1.9 vs ext/libuv/README.md in libuv-3.2.0

- old
+ new

@@ -1,11 +1,11 @@ ![libuv][libuv_banner] ## Overview libuv is a multi-platform support library with a focus on asynchronous I/O. It -was primarily developed for use by [Node.js](http://nodejs.org), but it's also +was primarily developed for use by [Node.js][], but it's also used by [Luvit](http://luvit.io/), [Julia](http://julialang.org/), [pyuv](https://github.com/saghul/pyuv), and [others](https://github.com/libuv/libuv/wiki/Projects-that-use-libuv). ## Feature highlights @@ -60,28 +60,38 @@ framework, which makes it possible to build the documentation in multiple formats. Show different supported building options: - $ make help +```bash +$ make help +``` Build documentation as HTML: - $ make html +```bash +$ make html +``` Build documentation as HTML and live reload it when it changes (this requires sphinx-autobuild to be installed and is only supported on Unix): - $ make livehtml +```bash +$ make livehtml +``` Build documentation as man pages: - $ make man +```bash +$ make man +``` Build documentation as ePub: - $ make epub +```bash +$ make epub +``` NOTE: Windows users need to use make.bat instead of plain 'make'. Documentation can be browsed online [here](http://docs.libuv.org). @@ -114,84 +124,139 @@ [MAINTAINERS](https://github.com/libuv/libuv/blob/master/MAINTAINERS.md) file, but are also available as git blob objects for easier use. Importing a key the usual way: - $ gpg --keyserver pool.sks-keyservers.net \ - --recv-keys AE9BC059 +```bash +$ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059 +``` Importing a key from a git blob object: - $ git show pubkey-saghul | gpg --import +```bash +$ git show pubkey-saghul | gpg --import +``` ### Verifying releases Git tags are signed with the developer's key, they can be verified as follows: - $ git verify-tag v1.6.1 +```bash +$ git verify-tag v1.6.1 +``` Starting with libuv 1.7.0, the tarballs stored in the [downloads site](http://dist.libuv.org/dist/) are signed and an accompanying signature file sit alongside each. Once both the release tarball and the signature file are downloaded, the file can be verified as follows: - $ gpg --verify libuv-1.7.0.tar.gz.sign +```bash +$ gpg --verify libuv-1.7.0.tar.gz.sign +``` ## Build Instructions For GCC there are two build methods: via autotools or via [GYP][]. GYP is a meta-build system which can generate MSVS, Makefile, and XCode backends. It is best used for integration into other projects. To build with autotools: - $ sh autogen.sh - $ ./configure - $ make - $ make check - $ make install +```bash +$ sh autogen.sh +$ ./configure +$ make +$ make check +$ make install +``` ### Windows -First, [Python][] 2.6 or 2.7 must be installed as it is required by [GYP][]. -If python is not in your path, set the environment variable `PYTHON` to its -location. For example: `set PYTHON=C:\Python27\python.exe` +Prerequisites: -To build with Visual Studio, launch a git shell (e.g. Cmd or PowerShell) -and run vcbuild.bat which will checkout the GYP code into build/gyp and -generate uv.sln as well as related project files. +* [Python 2.6 or 2.7][] as it is required + by [GYP][]. + If python is not in your path, set the environment variable `PYTHON` to its + location. For example: `set PYTHON=C:\Python27\python.exe` +* One of: + * [Visual C++ Build Tools][] + * [Visual Studio 2015 Update 3][], all editions + including the Community edition (remember to select + "Common Tools for Visual C++ 2015" feature during installation). + * [Visual Studio 2017][], any edition (including the Build Tools SKU). + **Required Components:** "MSbuild", "VC++ 2017 v141 toolset" and one of the + Windows SDKs (10 or 8.1). +* Basic Unix tools required for some tests, + [Git for Windows][] includes Git Bash + and tools which can be included in the global `PATH`. -To have GYP generate build script for another system, checkout GYP into the -project tree manually: +To build, launch a git shell (e.g. Cmd or PowerShell), run `vcbuild.bat` +(to build with VS2017 you need to explicitly add a `vs2017` argument), +which will checkout the GYP code into `build/gyp`, generate `uv.sln` +as well as the necesery related project files, and start building. - $ git clone https://chromium.googlesource.com/external/gyp.git build/gyp +```console +> vcbuild +``` +Or: + +```console +> vcbuild vs2017 +``` + +To run the tests: + +```console +> vcbuild test +``` + +To see all the options that could passed to `vcbuild`: + +```console +> vcbuild help +vcbuild.bat [debug/release] [test/bench] [clean] [noprojgen] [nobuild] [vs2017] [x86/x64] [static/shared] +Examples: + vcbuild.bat : builds debug build + vcbuild.bat test : builds debug build and runs tests + vcbuild.bat release bench: builds release build and runs benchmarks +``` + + ### Unix For Debug builds (recommended) run: - $ ./gyp_uv.py -f make - $ make -C out +```bash +$ ./gyp_uv.py -f make +$ make -C out +``` For Release builds run: - $ ./gyp_uv.py -f make - $ BUILDTYPE=Release make -C out +```bash +$ ./gyp_uv.py -f make +$ BUILDTYPE=Release make -C out +``` Run `./gyp_uv.py -f make -Dtarget_arch=x32` to build [x32][] binaries. ### OS X Run: - $ ./gyp_uv.py -f xcode - $ xcodebuild -ARCHS="x86_64" -project uv.xcodeproj \ - -configuration Release -target All +```bash +$ ./gyp_uv.py -f xcode +$ xcodebuild -ARCHS="x86_64" -project uv.xcodeproj \ + -configuration Release -target All +``` Using Homebrew: - $ brew install --HEAD libuv +```bash +$ brew install --HEAD libuv +``` Note to OS X users: Make sure that you specify the architecture you wish to build for in the "ARCHS" flag. You can specify more than one by delimiting with a space @@ -199,32 +264,38 @@ ### Android Run: - $ source ./android-configure NDK_PATH gyp - $ make -C out +```bash +$ source ./android-configure NDK_PATH gyp +$ make -C out +``` Note for UNIX users: compile your project with `-D_LARGEFILE_SOURCE` and `-D_FILE_OFFSET_BITS=64`. GYP builds take care of that automatically. ### Using Ninja To use ninja for build on ninja supported platforms, run: - $ ./gyp_uv.py -f ninja - $ ninja -C out/Debug #for debug build OR - $ ninja -C out/Release +```bash +$ ./gyp_uv.py -f ninja +$ ninja -C out/Debug #for debug build OR +$ ninja -C out/Release +``` ### Running tests Run: - $ ./gyp_uv.py -f make - $ make -C out - $ ./out/Debug/run-tests +```bash +$ ./gyp_uv.py -f make +$ make -C out +$ ./out/Debug/run-tests +``` ## Supported Platforms Check the [SUPPORTED_PLATFORMS file](SUPPORTED_PLATFORMS.md). @@ -242,9 +313,13 @@ See the [guidelines for contributing][]. [node.js]: http://nodejs.org/ [GYP]: http://code.google.com/p/gyp/ -[Python]: https://www.python.org/downloads/ [guidelines for contributing]: https://github.com/libuv/libuv/blob/master/CONTRIBUTING.md [libuv_banner]: https://raw.githubusercontent.com/libuv/libuv/master/img/banner.png [x32]: https://en.wikipedia.org/wiki/X32_ABI +[Python 2.6 or 2.7]: https://www.python.org/downloads/ +[Visual C++ Build Tools]: http://landinghub.visualstudio.com/visual-cpp-build-tools +[Visual Studio 2015 Update 3]: https://www.visualstudio.com/vs/older-downloads/ +[Visual Studio 2017]: https://www.visualstudio.com/downloads/ +[Git for Windows]: http://git-scm.com/download/win