Add installation instructions to README.md

README.md

@@ -16,6 +16,40 @@ The ICU homepage is http://site.icu-project.org/
 
 See also the CLDR homepage at http://cldr.unicode.org/
 
+## Installing PyICU
+
+  - Mac OS X
+    - Ensure ICU is installed and can be found by `pkg-config` (as `icu-config` was [deprecated](http://userguide.icu-project.org/howtouseicu#TOC-C-Makefiles) as of ICU 63.1), either by following [ICU build instructions](https://htmlpreview.github.io/?https://github.com/unicode-org/icu/blob/master/icu4c/readme.html#HowToBuild), or by using Homebrew:
+      ```sh
+      # install libicu (keg-only)
+      brew install pkg-config icu4c
+
+      # let setup.py discover keg-only icu4c via pkg-config
+      export PATH="/usr/local/opt/icu4c/bin:/usr/local/opt/icu4c/sbin:$PATH"
+      export PKG_CONFIG_PATH="$PKG_CONFIG_PATH:/usr/local/opt/icu4c/lib/pkgconfig"
+      ```
+    - Install PyICU **with the same C-compiler as your Python distribution** ([more info](https://github.com/ovalhub/pyicu/pull/140#issuecomment-782283491)):
+      ```sh
+      # EITHER - when using a gcc-built CPython (e.g. from Homebrew)
+      export CC="$(which gcc)" CXX="$(which g++)"
+      # OR - when using system CPython or another clang-based CPython, ensure system clang is used (for proper libstdc++ https://github.com/ovalhub/pyicu/issues/5#issuecomment-291631507):
+      unset CC CXX
+
+      # avoid wheels from previous runs or PyPI
+      pip install --no-binary=:pyicu: pyicu
+      ```
+
+  - Debian
+    ```sh
+    apt-get update
+
+    # EITHER - from apt directly https://packages.debian.org/source/stable/pyicu
+    apt-get install python3-icu
+    # OR - from source
+    apt-get install pkg-config libicu-dev
+    pip install --no-binary=:pyicu: pyicu
+    ```
+
 ## Building PyICU
 
 Before building PyICU the ICU libraries must be built and installed. Refer