Allow custom CFLAGS and update documentation on reducing size. (#2517)

Squashed commit Co-authored-by: Eric Jolibois <em.jolibois@gmail.com>

changes/2517-peterroelants.md

@@ -0,0 +1 @@
+Documentation update how to custom compile pydantic when using pip install, small change in `setup.py` to allow for custom CFLAGS when compiling.

docs/install.md

@@ -16,10 +16,13 @@ channel:
 conda install pydantic -c conda-forge
 ```
 
-*pydantic* can optionally be compiled with [cython](https://cython.org/) which should give a 30-50% performance
-improvement. 
+## Compiled with Cython
+
+*pydantic* can optionally be compiled with [cython](https://cython.org/) which should give a 30-50% performance improvement. 
+
+By default `pip install` provides optimized binaries via [PyPI](https://pypi.org/project/pydantic/#files) for Linux, MacOS and 64bit Windows.
+
 
-Binaries are available from [PyPI](https://pypi.org/project/pydantic/#files) for Linux, MacOS and 64bit Windows.
 If you're installing manually, install `cython` before installing *pydantic* and compilation should happen automatically.
 
 To test if *pydantic* is compiled run:
@@ -29,6 +32,27 @@ import pydantic
 print('compiled:', pydantic.compiled)
 ```
 
+### Performance vs package size trade-off
+
+Compiled binaries can increase the size of your Python environment. If for some reason you want to reduce the size of your *pydantic* installation you can avoid installing any binaries using the [`pip --no-binary`](https://pip.pypa.io/en/stable/cli/pip_install/#install-no-binary) option. Make sure `Cython` is not in your environment, or that you have the `SKIP_CYTHON` environment variable set to avoid re-compiling *pydantic* libraries:
+
+```bash
+SKIP_CYTHON=1 pip install --no-binary pydantic pydantic
+```
+!!! note
+    `pydantic` is repeated here intentionally, `--no-binary pydantic` tells `pip` you want no binaries for pydantic,
+    the next `pydantic` tells `pip` which package to install.
+
+Alternatively, you can re-compile *pydantic* with custom [build options](https://gcc.gnu.org/onlinedocs/gcc/Optimize-Options.html), this would require having the [`Cython`](https://pypi.org/project/Cython/) package installed before re-compiling *pydantic* with:
+```bash
+CFLAGS="-Os -g0 -s" pip install \
+  --no-binary pydantic \
+  --global-option=build_ext \
+  pydantic
+```
+
+## Optional dependencies
+
 *pydantic* has two optional dependencies:
 
 * If you require email validation you can add [email-validator](https://github.com/JoshData/python-email-validator)
@@ -46,6 +70,9 @@ pip install pydantic[email,dotenv]
 
 Of course, you can also install these requirements manually with `pip install email-validator` and/or `pip install`.
 
+
+## Install from repository
+
 And if you prefer to install *pydantic* directly from the repository:
 ```bash
 pip install git+git://github.com/samuelcolvin/pydantic@master#egg=pydantic

setup.py

@@ -82,7 +82,9 @@ if not any(arg in sys.argv for arg in ['clean', 'check']) and 'SKIP_CYTHON' not
         compiler_directives = {}
         if 'CYTHON_TRACE' in sys.argv:
             compiler_directives['linetrace'] = True
-        os.environ['CFLAGS'] = '-O3'
+        # Set CFLAG to all optimizations (-O3)
+        # Any additional CFLAGS will be appended. Only the last optimization flag will have effect
+        os.environ['CFLAGS'] = '-O3 ' + os.environ.get('CFLAGS', '')
         ext_modules = cythonize(
             'pydantic/*.py',
             exclude=['pydantic/generics.py'],