Repository: pypa/pip

Issue:
document how to set tmpdir
* Pip version: 9.0.1
* Python version: 3.5.3
* Operating system: Linux

### Description:

My `/tmp` directory is on a partition without enough space to build a (big) package.  From the documentation (and unfamiliarity with pip) I expected that specifying `--build` to another directory would move all of pip's temporary building activity to that directory:
```
pip3 install --build /lots/of/space thepackage
```
Of course, it did not.

Eventually I found out that setting `TMPDIR` to the desired directory would do it (in bash).

I recommend providing an option to specify the tmpdir, or (maybe better) saying something in the documentation about how to do this.   Perhaps, by adding to the documentation for `--build` something like perhaps: "The initial build will still take place in an OS-specified temporary directory (change this by setting TMPDIR)."


Discussion:
hey @xavfernandez i would like to fix this, could you guide me through this. ("First Timer on Github ")
@Riyuzakii, sorry for the delay.

I don't know how much you know about git, github, sphinx and tox but you'll have to:
  - fork pip
  - clone your fork
  - create a new git branch
  - update the documentation (in the `docs` directory)
  - install tox to build the documentation via `tox -e docs`
  - check the result in `docs/_build/html/`
  - commit your change and push it to your fork
  - finally open a pull request against pip master branch.

Let me know if you need clarification.
if its not fixed yet, i would like to take it up!
Hi @1byxero! Go ahead. @xavfernandez wrote a summary above.

Ping me by mentioning me on this issue if you need help. :)

So, if i understand the issue right, the issue is about providing a parameter for custom `temp` directory is not documented, but the is implemented.
And to fix it, all i need to do is add that in documentation.

Is that right? 
@pradyunsg 
Indeed.

As I understand, a documentation-only fix for this would be to add note to the documentation of 
`--build` that the `TMPDIR` environment variable has to be used to change the location of temporary builds that pip does.

And i think the changes should be made to `pip_install.rst` i.e [this file](https://github.com/1byxero/pip/blob/master/docs/reference/pip_install.rst)
Right?
@pradyunsg 
I'd prefer that they are made in the help text for `--build` (as an additional statement in help text) and in the file you've linked to. :)

https://github.com/pypa/pip/blob/e2b2f70ebb178916dacf3eb00195938960f2aa64/src/pip/_internal/cmdoptions.py#L428

@pradyunsg Hey, So to fix the issue I added the following text in the `help` argument of `-build` option and using tox to build the preview automatically added the same text in the documentation.

`Initial build would still take place in direcotry set by TMPDIR environment variable. To change this behavior, set appropriate directory by setting TMPDIR environment variable`

So basically I changed 

    build_dir = partial(
        Option,
        '-b', '--build', '--build-dir', '--build-directory',
        dest='build_dir',
        metavar='dir',
        help="Directory to unpack packages into and build in."
    )  # type: Any
to

    build_dir = partial(
        Option,
        '-b', '--build', '--build-dir', '--build-directory',
        dest='build_dir',
        metavar='dir',
        help="Directory to unpack packages into and build in. "
             "Initial build would still take place in direcotry set by TMPDIR "
             "environment variable, (TEMP on windows) To change this behavior,"
             "set appropriate directory by setting TMPDIR environment variable"
    )  # type: Any

I think thats enough to solve the issue, if not please let me know what else should i change before committing and creating a PR
On Windows it would be the `TEMP` environment variable, not `TMPDIR`, I guess...
@pfmoore Have updated, Thanks for the help :)
@xavfernandez @pradyunsg Should i go ahead and create a PR?
@1byxero Go ahead. :)

Resolving patch:
diff --git a/src/pip/_internal/cmdoptions.py b/src/pip/_internal/cmdoptions.py
--- a/src/pip/_internal/cmdoptions.py
+++ b/src/pip/_internal/cmdoptions.py
@@ -434,7 +434,10 @@ def only_binary():
     '-b', '--build', '--build-dir', '--build-directory',
     dest='build_dir',
     metavar='dir',
-    help='Directory to unpack packages into and build in.'
+    help='Directory to unpack packages into and build in. Note that '
+         'an initial build still takes place in a temporary directory. '
+         'The location of temporary directories can be controlled by setting '
+         'the TMPDIR environment variable (TEMP on Windows) appropriately.'
 )  # type: Any
 
 ignore_requires_python = partial(


Test patch: