From c8252fba9f771a82fe0dae4535c0accc2929935f Mon Sep 17 00:00:00 2001 From: Maria Mckinley Date: Mon, 22 May 2017 11:19:20 -0700 Subject: [PATCH 1/8] added a link to install dependencies in index --- index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.rst b/index.rst index e1338050e1..74783d12f8 100644 --- a/index.rst +++ b/index.rst @@ -12,7 +12,7 @@ Quick Start ----------- Here are the basic steps needed to get :ref:`set up ` and contribute a -patch: +patch. Please not you may have to :ref:`install dependencies ` first: 1. Install and set up :ref:`Git ` and other dependencies (see the :ref:`Get Setup ` page for detailed information). From 0df4f9627a484a248361d292778d0ad311e13324 Mon Sep 17 00:00:00 2001 From: Maria Mckinley Date: Mon, 22 May 2017 11:57:52 -0700 Subject: [PATCH 2/8] updated the coverage documentation to make it clearer --- coverage.rst | 22 +++++++++++++++------- 1 file changed, 15 insertions(+), 7 deletions(-) diff --git a/coverage.rst b/coverage.rst index 2bd509f628..48ff691aa7 100644 --- a/coverage.rst +++ b/coverage.rst @@ -75,16 +75,23 @@ provides very nice HTML output along with advanced features such as provided by the stdlib then you can by :ref:`using 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:: +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. This means that the most straightforward +way to run coverage may be to install coverage from source. + +Another reason you may want to do this is because the in-development version of +Python is bleeding-edge, and it is possible that the latest release version of +coverage.py will not work. + +For both of these use cases you should try using the in-development of coverage.py. +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 +installed copy. For this, you will need to use the full path to that installation. +But if you do not already have it installed then it is preferred you use a clone of coverage.py for gathering coverage results. If you are using a clone of coverage.py, the following should work (substitute @@ -95,7 +102,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 into the built copy of python, +and pip will not install there by default):: ./python -m coverage From 6a99b7cd15805df5a90560746723307f17d44d58 Mon Sep 17 00:00:00 2001 From: Maria Mckinley Date: Mon, 22 May 2017 13:34:49 -0700 Subject: [PATCH 3/8] making the purpose of the quick instructions more clear --- index.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/index.rst b/index.rst index 74783d12f8..aa7f5b30bc 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. Please not you may have to :ref:`install dependencies ` first: +patch. This as meant as a checklist, once you know the basics. For complete instructions +plaese see the `setup guide `. 1. Install and set up :ref:`Git ` and other dependencies (see the :ref:`Get Setup ` page for detailed information). From af7610895120468968afc586795b8c8912f50f0e Mon Sep 17 00:00:00 2001 From: Maria Mckinley Date: Mon, 22 May 2017 14:06:20 -0700 Subject: [PATCH 4/8] added make command to mac instructions and made steps more clear --- setup.rst | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/setup.rst b/setup.rst index e9ae80884f..46ca4ec202 100644 --- a/setup.rst +++ b/setup.rst @@ -181,20 +181,35 @@ 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 + 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, From 563c4cc03da1487e415deead19cae5b03ca45afb Mon Sep 17 00:00:00 2001 From: Maria Mckinley Date: Mon, 22 May 2017 14:49:03 -0700 Subject: [PATCH 5/8] added using virtual env to installing coverage instructions --- coverage.rst | 32 +++++++++++++++++--------------- 1 file changed, 17 insertions(+), 15 deletions(-) diff --git a/coverage.rst b/coverage.rst index 48ff691aa7..aec0b508d2 100644 --- a/coverage.rst +++ b/coverage.rst @@ -72,29 +72,31 @@ 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 `. 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. This means that the most straightforward -way to run coverage may be to install coverage from source. +into your default version of Python. One option is to use a virtual environment +to install coverage:: -Another reason you may want to do this is because the in-development version of -Python is bleeding-edge, and it is possible that the latest release version of -coverage.py will not work. + ./python.exe -m venv ../cpython-venv + source ../cpython-venv/bin/activate + pip install coverage -For both of these use cases you should try using the in-development of coverage.py. -To do this you should clone/check out the development version of coverage.py:: + +If this does not work for you for some reason, 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: 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. For this, you will need to use the full path to that installation. -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 an +installed copy. For this also, you will also need to use the full path to that installation. -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``):: @@ -102,8 +104,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 (note this must be installed into the built copy of python, -and pip will not install there by default):: +following instead (note this must be installed using the built copy of python, +such as by venv):: ./python -m coverage From f5c9818c636455b9ee614e6cafa46c361ed02bf1 Mon Sep 17 00:00:00 2001 From: Maria Mckinley Date: Mon, 22 May 2017 15:34:45 -0700 Subject: [PATCH 6/8] added some clarity --- coverage.rst | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/coverage.rst b/coverage.rst index aec0b508d2..a50138bb30 100644 --- a/coverage.rst +++ b/coverage.rst @@ -75,6 +75,12 @@ provides very nice HTML output along with advanced features such as provided by the stdlib then you can :ref:`use test.regrtest `. + +.. _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 @@ -84,7 +90,9 @@ to install coverage:: source ../cpython-venv/bin/activate pip install coverage - +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 https://docs.python.org/3/tutorial/venv.html. + If this does not work for you for some reason, 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: @@ -96,6 +104,11 @@ 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 an installed copy. For this also, you will also need to use the full path to that installation. +.. _coverage_usage: + +Basic Usage +''''''''''' + The following command will tell you if your copy of coverage works (substitute ``COVERAGEDIR`` with the directory where your clone exists, e.g. ``../coveragepy``):: From 83e77517f794a341bce7865b2b07c45a9f28602e Mon Sep 17 00:00:00 2001 From: Maria Mckinley Date: Tue, 23 May 2017 10:50:22 -0700 Subject: [PATCH 7/8] made changes per code review --- coverage.rst | 17 +++++++++-------- index.rst | 6 +++--- 2 files changed, 12 insertions(+), 11 deletions(-) diff --git a/coverage.rst b/coverage.rst index a50138bb30..77551675ee 100644 --- a/coverage.rst +++ b/coverage.rst @@ -90,19 +90,20 @@ to install coverage:: source ../cpython-venv/bin/activate pip install coverage -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 https://docs.python.org/3/tutorial/venv.html. +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 -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: +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 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 an -installed copy. For this also, you will also need to use the full path to that 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: @@ -117,7 +118,7 @@ The following command will tell you if your copy of coverage works (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 (note this must be installed using the built copy of python, +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 aa7f5b30bc..824cfda403 100644 --- a/index.rst +++ b/index.rst @@ -9,11 +9,11 @@ that maintains Python. We welcome your contributions to Python! Quick Reference ------------ +--------------- Here are the basic steps needed to get :ref:`set up ` and contribute a -patch. This as meant as a checklist, once you know the basics. For complete instructions -plaese see the `setup guide `. +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). From 3042674eb81e38d7ccc341c915ba7ae938150ee6 Mon Sep 17 00:00:00 2001 From: Maria Mckinley Date: Tue, 23 May 2017 11:16:06 -0700 Subject: [PATCH 8/8] more changes per code review --- coverage.rst | 5 ++++- setup.rst | 13 +++++++++++++ 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/coverage.rst b/coverage.rst index 77551675ee..50626704c9 100644 --- a/coverage.rst +++ b/coverage.rst @@ -86,10 +86,13 @@ 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.exe -m venv ../cpython-venv + ./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. diff --git a/setup.rst b/setup.rst index 46ca4ec202..59ab621602 100644 --- a/setup.rst +++ b/setup.rst @@ -211,6 +211,19 @@ 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, just ask for assistance on the core-mentorship list. If working on bug