From 2e2edf4f112478ffa3398452a9f862ed91daacbb Mon Sep 17 00:00:00 2001
From: Peter Roelants <Peter.roelants@gmail.com>
Date: Fri, 4 Jun 2021 21:42:49 +0200
Subject: [PATCH] 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 |  1 +
 docs/install.md               | 33 ++++++++++++++++++++++++++++++---
 setup.py                      |  4 +++-
 3 files changed, 34 insertions(+), 4 deletions(-)
 create mode 100644 changes/2517-peterroelants.md

diff --git a/changes/2517-peterroelants.md b/changes/2517-peterroelants.md
new file mode 100644
index 0000000..67eca39
--- /dev/null
+++ b/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.
diff --git a/docs/install.md b/docs/install.md
index bc1940b..0793196 100644
--- a/docs/install.md
+++ b/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
diff --git a/setup.py b/setup.py
index 52baae2..e93107b 100644
--- a/setup.py
+++ b/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'],