diff --git a/README.rst b/README.rst index 08dfe5c..6c885d3 100644 --- a/README.rst +++ b/README.rst @@ -63,8 +63,9 @@ Install PyPy ^^^^ -`PyPy `__ is the fastest way to run your Falcon app. However, note that -only the PyPy 2.7 compatible release is currently supported. +`PyPy `__ is the fastest way to run your Falcon app. +However, note that only the PyPy 2.7 compatible release is currently +supported. .. code:: bash @@ -74,14 +75,29 @@ CPython ^^^^^^^ Falcon also fully supports -`CPython `__ 2.6, 2.7, 3.3, 3.4, and -3.5. Under CPython, Falcon will compile itself with Cython, if -available, for an extra speed boost. The following will make sure Cython -is installed first, and that you always have the latest and greatest. +`CPython `__ 2.6-3.5. + +A universal wheel is available on PyPI for the the Falcon framework. +Installing it is as simple as: .. code:: bash - $ pip install --upgrade cython falcon + $ pip install falcon + +Installing the wheel is a great way to get up and running with Falcon +quickly in a development environment, but for an extra speed boost when +deploying your application in production, Falcon can compile itself with +Cython. + +The following commands tell pip to install Cython, and then to invoke +Falcon's ``setup.py``, which will in turn detect the presence of Cython +and then compile (AKA cythonize) the Falcon framework with the system's +default C compiler. + +.. code:: bash + + $ pip install cython + $ pip install --no-binary :all: falcon **Installing on OS X** @@ -92,21 +108,19 @@ with this command: $ xcode-select --install -The Xcode 5.1 CLang compiler treats unrecognized command-line options as +The Clang compiler treats unrecognized command-line options as errors; this can cause problems under Python 2.6, for example: .. code:: bash clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future] -You can work around errors caused by unused arguments by setting some -environment variables: +You might also see warnings about unused functions. You can work around +these issues by setting additional Clang C compiler flags as follows: .. code:: bash - $ export CFLAGS=-Qunused-arguments - $ export CPPFLAGS=-Qunused-arguments - $ pip install cython falcon + $ export CFLAGS="-Qunused-arguments -Wno-unused-function" Test ---- diff --git a/doc/user/install.rst b/doc/user/install.rst index 3eaed88..68c0aa7 100644 --- a/doc/user/install.rst +++ b/doc/user/install.rst @@ -3,60 +3,67 @@ Installation ============ -Install from PyPI ------------------ +PyPy +---- -If available, Falcon will compile itself with Cython for an extra -speed boost. The following will make sure Cython is installed first, and -that you always have the latest and greatest. +`PyPy `__ is the fastest way to run your Falcon app. +However, note that only the PyPy 2.7 compatible release is currently +supported. .. code:: bash - $ pip install --upgrade cython falcon + $ pip install falcon -Note that if you are running on PyPy, you won't need Cython, so you can just -type: +CPython +------- + +Falcon also fully supports +`CPython `__ 2.6-3.5. + +A universal wheel is available on PyPI for the the Falcon framework. +Installing it is as simple as: .. code:: bash - $ pip install --upgrade falcon + $ pip install falcon -.. note:: +Installing the wheel is a great way to get up and running with Falcon +quickly in a development environment, but for an extra speed boost when +deploying your application in production, Falcon can compile itself with +Cython. - When using Cython, you should always recompile Falcon after - upgrading Python. To do this, simply run: +The following commands tell pip to install Cython, and then to invoke +Falcon's ``setup.py``, which will in turn detect the presence of Cython +and then compile (AKA cythonize) the Falcon framework with the system's +default C compiler. - .. code:: bash +.. code:: bash - $ pip install --force-reinstall --upgrade cython - $ pip install --force-reinstall --upgrade falcon + $ pip install cython + $ pip install --no-binary :all: falcon -Installing Cython on OS X -------------------------- +**Installing on OS X** -In order to get Cython working on OS X Mavericks with Xcode 5.1, you will -first need to set up Xcode Command Line Tools. Install them with -this command: +Xcode Command Line Tools are required to compile Cython. Install them +with this command: .. code:: bash $ xcode-select --install -The Xcode 5.1 CLang compiler treats unrecognized command-line options as +The Clang compiler treats unrecognized command-line options as errors; this can cause problems under Python 2.6, for example: .. code:: bash clang: error: unknown argument: '-mno-fused-madd' [-Wunused-command-line-argument-hard-error-in-future] -You can work around errors caused by unused arguments by setting some -environment variables: +You might also see warnings about unused functions. You can work around +these issues by setting additional Clang C compiler flags as follows: .. code:: bash - $ export CFLAGS=-Qunused-arguments - $ export CPPFLAGS=-Qunused-arguments - $ pip install cython falcon + $ export CFLAGS="-Qunused-arguments -Wno-unused-function" WSGI Server @@ -69,7 +76,7 @@ an async library that works well with both Gunicorn and uWSGI. .. code:: bash - $ pip install --upgrade gevent [gunicorn|uwsgi] + $ pip install gevent [gunicorn|uwsgi] Source Code