deps/uv/README.md

   1 # libuv
   2
   3 libuv is a multi-platform support library with a focus on asynchronous I/O. It
   4 was primarily developed for use by [Node.js](http://nodejs.org), but it's also
   5 used by Mozilla's [Rust language](http://www.rust-lang.org/),
   6 [Luvit](http://luvit.io/), [Julia](http://julialang.org/),
   7 [pyuv](https://crate.io/packages/pyuv/), and [others](https://github.com/joyent/libuv/wiki/Projects-that-use-libuv).
   8
   9 ## Feature highlights
  10
  11  * Full-featured event loop backed by epoll, kqueue, IOCP, event ports.
  12
  13  * Asynchronous TCP and UDP sockets
  14
  15  * Asynchronous DNS resolution
  16
  17  * Asynchronous file and file system operations
  18
  19  * File system events
  20
  21  * ANSI escape code controlled TTY
  22
  23  * IPC with socket sharing, using Unix domain sockets or named pipes (Windows)
  24
  25  * Child processes
  26
  27  * Thread pool
  28
  29  * Signal handling
  30
  31  * High resolution clock
  32
  33  * Threading and synchronization primitives
  34
  35
  36 ## Community
  37
  38  * [Mailing list](http://groups.google.com/group/libuv)
  39
  40 ## Documentation
  41
  42  * [include/uv.h](https://github.com/joyent/libuv/blob/master/include/uv.h)
  43    &mdash; API documentation in the form of detailed header comments.
  44  * [An Introduction to libuv](http://nikhilm.github.com/uvbook/)
  45    &mdash; An overview of libuv with tutorials.
  46  * [LXJS 2012 talk](http://www.youtube.com/watch?v=nGn60vDSxQ4)
  47    &mdash; High-level introductory talk about libuv.
  48  * [Tests and benchmarks](https://github.com/joyent/libuv/tree/master/test)
  49    &mdash; API specification and usage examples.
  50  * [libuv-dox](https://github.com/thlorenz/libuv-dox)
  51    &mdash; Documenting types and methods of libuv, mostly by reading uv.h.
  52
  53 ## Build Instructions
  54
  55 For GCC there are two methods building: via autotools or via [GYP][].
  56 GYP is a meta-build system which can generate MSVS, Makefile, and XCode
  57 backends. It is best used for integration into other projects.
  58
  59 To build with autotools:
  60
  61     $ sh autogen.sh
  62     $ ./configure
  63     $ make
  64     $ make check
  65     $ make install
  66
  67 ### Windows
  68
  69 First, Python 2.6 or 2.7 must be installed as it is required by [GYP][].
  70
  71 Also, the directory for the preferred Python executable must be specified
  72 by the `PYTHON` or `Path` environment variables.
  73
  74 To build with Visual Studio, launch a git shell (e.g. Cmd or PowerShell)
  75 and run vcbuild.bat which will checkout the GYP code into build/gyp and
  76 generate uv.sln as well as related project files.
  77
  78 To have GYP generate build script for another system, checkout GYP into the
  79 project tree manually:
  80
  81     $ mkdir -p build
  82     $ git clone https://git.chromium.org/external/gyp.git build/gyp
  83
  84 ### Unix
  85
  86 Run:
  87
  88     $ ./gyp_uv.py -f make
  89     $ make -C out
  90
  91 ### OS X
  92
  93 Run:
  94
  95     $ ./gyp_uv.py -f xcode
  96     $ xcodebuild -project uv.xcodeproj -configuration Release -target All
  97
  98 ### Android
  99
 100 Run:
 101
 102     $ source ./android-configure NDK_PATH gyp
 103     $ make -C out
 104
 105 Note for UNIX users: compile your project with `-D_LARGEFILE_SOURCE` and
 106 `-D_FILE_OFFSET_BITS=64`. GYP builds take care of that automatically.
 107
 108 ### Running tests
 109
 110 Run:
 111
 112     $ ./gyp_uv.py -f make
 113     $ make -C out
 114     $ ./out/Debug/run-tests
 115
 116 ## Supported Platforms
 117
 118 Microsoft Windows operating systems since Windows XP SP2. It can be built
 119 with either Visual Studio or MinGW. Consider using
 120 [Visual Studio Express 2010][] or later if you do not have a full Visual
 121 Studio license.
 122
 123 Linux using the GCC toolchain.
 124
 125 OS X using the GCC or XCode toolchain.
 126
 127 Solaris 121 and later using GCC toolchain.
 128
 129 ## patches
 130
 131 See the [guidelines for contributing][].
 132
 133 [node.js]: http://nodejs.org/
 134 [GYP]: http://code.google.com/p/gyp/
 135 [Visual Studio Express 2010]: http://www.microsoft.com/visualstudio/eng/products/visual-studio-2010-express
 136 [guidelines for contributing]: https://github.com/joyent/libuv/blob/master/CONTRIBUTING.md