diff --git a/coverage.rst b/coverage.rst index 2bd509f628..50626704c9 100644 --- a/coverage.rst +++ b/coverage.rst @@ -72,22 +72,48 @@ Using coverage.py One of the most popular third-party coverage tools is `coverage.py`_ which provides very nice HTML output along with advanced features such as :ref:`branch coverage `. If you prefer to stay with tools only -provided by the stdlib then you can by :ref:`using test.regrtest +provided by the stdlib then you can :ref:`use test.regrtest `. -Because the in-development version of Python is bleeding-edge, it is possible -that the latest release version of coverage.py will not work. In that case you -should try using the in-development of coverage.py to see if it has been -updated as needed. To do this you should clone/check out the development version -of coverage.py:: + +.. _install_coverage: + +Install Coverage +'''''''''''''''' + +By default, pip will not install into the in-development version of Python you +just built, and this built version of Python will not see packages installed +into your default version of Python. One option is to use a virtual environment +to install coverage:: + + ./python -m venv ../cpython-venv + source ../cpython-venv/bin/activate + pip install coverage + +On :ref:`most ` Mac OS X systems, replace :file:`./python` +with :file:`./python.exe`. On Windows, use :file:`python.bat`. + +You can now use python without the ./ for the rest of these instructions, as +long as your venv is activated. For more info on venv see `Virtual Envrionment +`_ documentation. + +If this does not work for you for some reason, you should try using the +in-development version of coverage.py to see if it has been updated as needed. +To do this you should clone/check out the development version of coverage.py: hg clone https://bitbucket.org/ned/coveragepy -Another option is to use an installed copy of coverage.py if you already have an -installed copy. But if you do not already have it installed then it is preferred -you use a clone of coverage.py for gathering coverage results. +You will need to use the full path to the installation. + +Another option is to use an installed copy of coverage.py, if you already have +it. For this, you will again need to use the full path to that installation. + +.. _coverage_usage: + +Basic Usage +''''''''''' -If you are using a clone of coverage.py, the following should work (substitute +The following command will tell you if your copy of coverage works (substitute ``COVERAGEDIR`` with the directory where your clone exists, e.g. ``../coveragepy``):: @@ -95,7 +121,8 @@ If you are using a clone of coverage.py, the following should work (substitute Coverage.py will print out a little bit of helper text verifying that everything is working. If you are using an installed copy, you can do the -following instead:: +following instead (note this must be installed using the built copy of Python, +such as by venv):: ./python -m coverage diff --git a/index.rst b/index.rst index e1338050e1..824cfda403 100644 --- a/index.rst +++ b/index.rst @@ -8,11 +8,12 @@ to Python_ -- for both new and experienced contributors. It is that maintains Python. We welcome your contributions to Python! -Quick Start ------------ +Quick Reference +--------------- Here are the basic steps needed to get :ref:`set up ` and contribute a -patch: +patch. This is meant as a checklist, once you know the basics. For complete +instructions please see the `setup guide `. 1. Install and set up :ref:`Git ` and other dependencies (see the :ref:`Get Setup ` page for detailed information). diff --git a/setup.rst b/setup.rst index e9ae80884f..59ab621602 100644 --- a/setup.rst +++ b/setup.rst @@ -181,20 +181,48 @@ OpenSSL which means that you will not be able to build the ``_ssl`` extension. One solution is to install these libraries from a third-party package manager, like Homebrew_ or MacPorts_, and then add the appropriate paths for the header and library files to your ``configure`` command. For example, -with Homebrew:: + +with **Homebrew**:: $ brew install openssl xz + +and configure:: + $ CPPFLAGS="-I$(brew --prefix openssl)/include" \ LDFLAGS="-L$(brew --prefix openssl)/lib" \ ./configure --with-pydebug -or MacPorts:: +and make:: + + $ make -s -j2 + +or **MacPorts**:: $ sudo port install openssl xz + +and configure:: + $ CPPFLAGS="-I/opt/local/include" \ LDFLAGS="-L/opt/local/lib" \ ./configure --with-pydebug +and make:: + + $ make -s -j2 + + +This will build CPython with only warnings and errors being printed to +stderr and utilize up to 2 CPU cores. If you are using a multi-core machine +with more than 2 cores (or a single-core machine), you can adjust the number +passed into the ``-j`` flag to match the number of cores you have. + +Do take note of what modules were **not** built as stated at the end of your +build. More than likely you are missing a dependency for the module(s) that +were not built, and so you can install the dependencies and re-run both +``configure`` and ``make`` (if available for your OS). +Otherwise the build failed and thus should be fixed (at least with a bug being +filed on the `issue tracker`_). + There will sometimes be optional modules added for a new release which won't yet be identified in the OS level build dependencies. In those cases,