doc: format README

PR-URL: https://github.com/libuv/libuv/pull/1284
Reviewed-By: Bartosz Sosnowski <bartosz@janeasystems.com>
Reviewed-By: Ben Noordhuis <info@bnoordhuis.nl>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Saúl Ibarra Corretgé <saghul@gmail.com>
This commit is contained in:
Refael Ackermann 2017-07-04 09:08:34 -04:00 committed by Saúl Ibarra Corretgé
parent 0953bf0dad
commit 80d3b95f57

View File

@ -3,7 +3,7 @@
## Overview ## Overview
libuv is a multi-platform support library with a focus on asynchronous I/O. It 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/), 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). [pyuv](https://github.com/saghul/pyuv), and [others](https://github.com/libuv/libuv/wiki/Projects-that-use-libuv).
@ -62,24 +62,34 @@ formats.
Show different supported building options: Show different supported building options:
$ make help ```bash
$ make help
```
Build documentation as HTML: Build documentation as HTML:
$ make html ```bash
$ make html
```
Build documentation as HTML and live reload it when it changes (this requires Build documentation as HTML and live reload it when it changes (this requires
sphinx-autobuild to be installed and is only supported on Unix): sphinx-autobuild to be installed and is only supported on Unix):
$ make livehtml ```bash
$ make livehtml
```
Build documentation as man pages: Build documentation as man pages:
$ make man ```bash
$ make man
```
Build documentation as ePub: Build documentation as ePub:
$ make epub ```bash
$ make epub
```
NOTE: Windows users need to use make.bat instead of plain 'make'. NOTE: Windows users need to use make.bat instead of plain 'make'.
@ -116,25 +126,32 @@ file, but are also available as git blob objects for easier use.
Importing a key the usual way: Importing a key the usual way:
$ gpg --keyserver pool.sks-keyservers.net \ ```bash
--recv-keys AE9BC059 $ gpg --keyserver pool.sks-keyservers.net --recv-keys AE9BC059
```
Importing a key from a git blob object: Importing a key from a git blob object:
$ git show pubkey-saghul | gpg --import ```bash
$ git show pubkey-saghul | gpg --import
```
### Verifying releases ### Verifying releases
Git tags are signed with the developer's key, they can be verified as follows: 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 Starting with libuv 1.7.0, the tarballs stored in the
[downloads site](http://dist.libuv.org/dist/) are signed and an accompanying [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 sit alongside each. Once both the release tarball and the
signature file are downloaded, the file can be verified as follows: 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 ## Build Instructions
@ -144,18 +161,20 @@ backends. It is best used for integration into other projects.
To build with autotools: To build with autotools:
$ sh autogen.sh ```bash
$ ./configure $ sh autogen.sh
$ make $ ./configure
$ make check $ make
$ make install $ make check
$ make install
```
### Windows ### Windows
Prerequisites: Prerequisites:
* [Python 2.6 or 2.7][] as it is required * [Python 2.6 or 2.7][] as it is required
by [GYP][]. by [GYP][].
If python is not in your path, set the environment variable `PYTHON` to its If python is not in your path, set the environment variable `PYTHON` to its
location. For example: `set PYTHON=C:\Python27\python.exe` location. For example: `set PYTHON=C:\Python27\python.exe`
* One of: * One of:
@ -207,13 +226,17 @@ Examples:
For Debug builds (recommended) run: For Debug builds (recommended) run:
$ ./gyp_uv.py -f make ```bash
$ make -C out $ ./gyp_uv.py -f make
$ make -C out
```
For Release builds run: For Release builds run:
$ ./gyp_uv.py -f make ```bash
$ BUILDTYPE=Release make -C out $ ./gyp_uv.py -f make
$ BUILDTYPE=Release make -C out
```
Run `./gyp_uv.py -f make -Dtarget_arch=x32` to build [x32][] binaries. Run `./gyp_uv.py -f make -Dtarget_arch=x32` to build [x32][] binaries.
@ -221,13 +244,17 @@ Run `./gyp_uv.py -f make -Dtarget_arch=x32` to build [x32][] binaries.
Run: Run:
$ ./gyp_uv.py -f xcode ```bash
$ xcodebuild -ARCHS="x86_64" -project uv.xcodeproj \ $ ./gyp_uv.py -f xcode
-configuration Release -target All $ xcodebuild -ARCHS="x86_64" -project uv.xcodeproj \
-configuration Release -target All
```
Using Homebrew: Using Homebrew:
$ brew install --HEAD libuv ```bash
$ brew install --HEAD libuv
```
Note to OS X users: Note to OS X users:
@ -239,8 +266,10 @@ Make sure that you specify the architecture you wish to build for in the
Run: Run:
$ source ./android-configure NDK_PATH gyp ```bash
$ make -C out $ source ./android-configure NDK_PATH gyp
$ make -C out
```
Note for UNIX users: compile your project with `-D_LARGEFILE_SOURCE` and Note for UNIX users: compile your project with `-D_LARGEFILE_SOURCE` and
`-D_FILE_OFFSET_BITS=64`. GYP builds take care of that automatically. `-D_FILE_OFFSET_BITS=64`. GYP builds take care of that automatically.
@ -249,18 +278,22 @@ Note for UNIX users: compile your project with `-D_LARGEFILE_SOURCE` and
To use ninja for build on ninja supported platforms, run: To use ninja for build on ninja supported platforms, run:
$ ./gyp_uv.py -f ninja ```bash
$ ninja -C out/Debug #for debug build OR $ ./gyp_uv.py -f ninja
$ ninja -C out/Release $ ninja -C out/Debug #for debug build OR
$ ninja -C out/Release
```
### Running tests ### Running tests
Run: Run:
$ ./gyp_uv.py -f make ```bash
$ make -C out $ ./gyp_uv.py -f make
$ ./out/Debug/run-tests $ make -C out
$ ./out/Debug/run-tests
```
## Supported Platforms ## Supported Platforms