Merge pull request #277 from PyO3/doc_link_args

Add Documentation on build and linker args

guide/src/SUMMARY.md

@@ -1,12 +1,12 @@
 # Summary
 
-- [Get Started](./overview.md)
-- [Type Conversions](./conversions.md)
-- [Python Exception](./exception.md)
-- [Python Module](./module.md)
-- [Python Function](./function.md)
-- [Python Class](./class.md)
-- [Parallelism](./parallelism.md)
-- [Debugging](./debugging.md)
-- [Distribution](./distribution.md)
-- [Appendix: Pyo3 and rust-cpython](./rust-cpython.md)
+- [Get Started](get_started.md)
+- [Type Conversions](conversions.md)
+- [Python Exception](exception.md)
+- [Python Module](module.md)
+- [Python Function](function.md)
+- [Python Class](class.md)
+- [Parallelism](parallelism.md)
+- [Debugging](debugging.md)
+- [Building and Distribution](building-and-distribution.md)
+- [Appendix: Pyo3 and rust-cpython](rust-cpython.md)

guide/src/building-and-distribution.md

@@ -0,0 +1,39 @@
+# Building and Distribution
+
+## Python version
+
+pyo3 uses a build script to determine the python version and set the correct linker arguments. By default it uses the `python3` executable. With the `python2` feature it uses the `python2` executable. You can override the python interpreter by setting `PYTHON_SYS_EXECUTABLE`. Note that you still need to activate the `python2` with  `PYTHON_SYS_EXECUTABLE=python2` (see [pyo3/pyo3#276](https://github.com/PyO3/pyo3/issues/276) for details).
+
+## Linking
+
+Different linker arguments must be set for libraries/extension modules and binaries, which includes both standalone binaries and tests. (More specifically, binaries must be told where to find libpython and libraries must not link to libpython for [manylinux](https://www.python.org/dev/peps/pep-0513/) compliance).
+
+Since pyo3's build script can't know whether you're building a binary or a library, you have to activate the `extension-module` feature to get the build options for a library, or it'll default to binary.
+
+If you have e.g. a library crate and a profiling crate alongside, you need to use optional features. E.g. you put the following in the library crate:
+
+```toml
+[dependencies]
+pyo3 = "0.5.0"
+
+[lib]
+name = "hyperjson"
+crate-type = ["rlib", "cdylib"]
+
+[features]
+default = ["pyo3/extension-module"]
+```
+
+And this in the profiling crate:
+
+```toml
+[dependencies]
+my_main_crate = { path = "..", default-features = false }
+pyo3 = "0.5.0"
+```
+
+On linux/mac you might have to change `LD_LIBRARY_PATH` to include libpython, while on windows you might need to set `LIB` to include `pythonxy.lib` (where x and y are major and minor version), which is normally either in the `libs` or `Lib` folder of a python installation.
+
+## Distribution
+
+There are two ways to distribute your module as python package: The old [setuptools-rust](https://github.com/PyO3/setuptools-rust) and the new [pyo3-pack](https://github.com/pyo3/pyo3-pack). setuptools-rust needs some configuration files (`setup.py`,  `MANIFEST.in`, `build-wheels.sh`, etc.) and external tools (docker, twine). pyo3-pack doesn't need any configuration files. It can not yet build sdist though ([pyo3/pyo3-pack#2](https://github.com/PyO3/pyo3-pack/issues/2)).

guide/src/debugging.md

@@ -18,6 +18,3 @@ cargo rustc --profile=check -- -Z unstable-options --pretty=expanded -Z trace-ma
 
 See [cargo expand](https://github.com/dtolnay/cargo-expand) for a more elaborate version of those commands.
 
-## Linking
-
-When building, you can set `PYTHON_SYS_EXECUTABLE` to the python interpreter that pyo3 should be linked to. You might need to set the `python2` or `python3` feature accordingly. On linux/mac you might have to change `LD_LIBRARY_PATH` to include libpython, while on windows you might need to set `LIB` to include `pythonxy.lib` (where x and y are major and minor version), which is normally either in the `libs` or `Lib` folder of a python installation. Also make sure that python is in `PATH` when you're not using  `PYTHON_SYS_EXECUTABLE`.

guide/src/distribution.md

@@ -1,3 +0,0 @@
-# Distribution
-
-There are two way to distribute your module as python package: The old [setuptools-rust](https://github.com/PyO3/setuptools-rust) and the new [pyo3-pack](https://github.com/pyo3/pyo3-pack). setuptools-rust needs some configuration files (`setup.py`,  `MANIFEST.in`, `build-wheels.sh`, etc.) and external tools (docker, twine). pyo3-pack doesn't need any configuration files. It can not yet build sdist though ([pyo3/pyo3-pack#2](https://github.com/PyO3/pyo3-pack/issues/2)).