Updated installation instructions for Python wrappers

Author: lballabio

install/linux-python.shtml

@@ -5,100 +5,111 @@ title: QuantLib-Python Installation on Linux
 
 <h1 class="center">QuantLib-Python installation on Linux</h1>
 
-<h2>Installation from PyPI</h2>
+<h2>Installation from PyPI (recommended)</h2>
 
-<p>If you don't need to modify the wrappers, you might want to try
-installing a precompiled binary version.  The availability of binaries
-depend on your operating system; to try to install them, first make
-sure you have the latest version of <code>pip</code> by running:</p>
+<p>If you don't need to modify the wrappers, you can install a
+precompiled wheel from PyPI.  Once you have activated the Python
+environment you want to use, make sure you have the latest version
+of <code>pip</code> by running:</p>
 <pre>
   python -m pip install -U pip
 </pre>
-<p>and then run:</p>
+<p>(note that your Python interpreter might be named <code>python3</code> instead) and then run:</p>
 <pre>
   python -m pip install QuantLib
 </pre>
-<p>(If you have multiple versions of Python installed, run the above
-with the one you want to use QuantLib with.) If a binary package is
-available for your system, it will be installed and you will be able
-to leave this page and use it right away; if not, you'll have to
-compile it yourself as described in the next section.</p>
+<p>If a wheel is available for your system (which is likely)
+it will be installed and you will be able to leave this page and use
+it right away; if not, you'll have to compile it yourself as described
+in the next section.</p>
 
 <h2>Installation from a released version</h2>
 
 <p>The following assumes that you already installed
-QuantLib. Instructions for that are available
-at <a href="http://quantlib.org/install/linux.shtml">http://quantlib.org/install/linux.shtml</a>;
-please make sure that you performed all listed steps.</p>
-
-<p>You can download released QuantLib-SWIG versions from GitHub
-at <a href="https://github.com/lballabio/QuantLib-SWIG/releases">https://github.com/lballabio/QuantLib-SWIG/releases</a>.</p>
-
-<p>Once you have the tarball, extract it by executing:</p>
+QuantLib; instructions are available
+at <a href="http://quantlib.org/install/linux.shtml">http://quantlib.org/install/linux.shtml</a></p>
+
+<h3>Setup</h3>
+
+<p>Before compiling the wrappers, you'll need to set up an appropriate
+environment:</p>
+<ul>
+  <li>Some of the commands you'll run will need to
+    invoke <code>quantlib-config</code> (which was installed with
+    QuantLib) to find out what flags should be passed to the compiler
+    and linker; they will also include the additional include
+    directories you might have specified when you built QuantLib, so
+    you'll be covered even if you have, say, Boost in a non-standard
+    place. This means that you must ensure
+    that <code>quantlib-config</code> is in your executable path.</li>
+  <li>You'll need to install a few Python modules.  It's good practice
+    to install them in a new virtual environment, to avoid possible
+    conflicts with your system Python installation.  This also helps
+    in case you have multiple versions of Python on your machine.  You
+    can create the virtual environment with
 <pre>
-tar xzf QuantLib-SWIG-1.7.tar.gz
+  python3 -m venv .venv
 </pre>
-<p>(1.7 is the most recent version at the time of this writing; you
-might have downloaded another one.) This creates a
-folder <code>QuantLib-SWIG-1.7</code>; enter it and configure QuantLib by
-executing:</p>
+    and activate it with
 <pre>
-  cd QuantLib-SWIG-1.7
-  ./configure
+  . .venv/bin/activate
 </pre>
-
-<p>Contrary to popular belief, working from a released tarball doesn't
-require you to have SWIG installed.  After configuration, you can just
-run</p>
+    (mind the single dot at the beginning of the line.)  Once the
+    environment is active, run
 <pre>
-  make -C Python
-  sudo make -C Python install
+  pip install setuptools build tox pytest
 </pre>
-
-<p>There are a few of caveats to the above. <strong>The first</strong>
-is that the <code>./configure</code> command will need to
-invoke <code>quantlib-config</code> (which was installed with
-QuantLib) to find out what flags should be passed to the compiler and
-linker; they will also include the additional include directories you
-might have specified when you built QuantLib, so you'll be covered
-even if you have, say, Boost in a non-standard place. This means
-that <code>quantlib-config</code> must be in your path.</p>
-
-<p><strong>The second</strong> is that the call
-to <code>./configure</code> as written above will find the system
-installation of Python.  If you want to use a different one (for
-instance because you installed different Python versions, or you want to use an
-Anaconda installation) you must pass the location of your chosen
-Python interpreter to <code>./configure</code>; for instance, if you
-have Python 3.9 installed as <code>/usr/local/bin/python3.9</code>, you'll
-have to run:</p>
+    If you're using <code>conda</code> to manage your environments,
+    you know what to do instead.
+  </li>
+  <li>You'll also need the Python development files installed (that
+    is, <code>python.h</code> and so on). They might be available by
+    default; but if not, you'll have to figure out how to get them. On
+    Ubuntu, for instance, you would install them with:
 <pre>
-  ./configure PYTHON=/usr/local/bin/python3.9
+  sudo apt-get install python3-dev
 </pre>
+    Similar packages should be available for most other
+    distributions.</li>
+  <li>Contrary to popular belief, working from a released
+    tarball <strong>doesn't require you to have SWIG
+    installed</strong>.</li>
+</ul>
+
+<h3>Compilation</h3>
+
+<p>You can download released QuantLib-SWIG versions from GitHub
+  at <a href="https://github.com/lballabio/QuantLib-SWIG/releases">https://github.com/lballabio/QuantLib-SWIG/releases</a>.
+  You should download the same version as the version of QuantLib you
+  installed; for the sake of example, I'll use version 1.36 which is
+  the most recent version at the time of this writing.
+</p>
 
-<p><strong>The third</strong> is that, unfortunately, at this
-time <code>make install</code> ignores any prefix you might pass
-to <code>./configure</code> and always installs to the default
-location, which requires you to use <code>sudo</code> as I wrote
-above. If you don't have admin rights, you'll have to look into
-<code>Python/Makefile</code> and pass your prefix
-to <code>setup.py.</code></p>
-
-<p>Of course, you'll also need the Python development files installed
-(that is, <code>python.h</code> and so on). They might be available by
-default; but if not, you'll have to figure out how to get them. On
-Ubuntu, for instance, you would install them with:</p>
+<p>Once you have the tarball, extract it by executing</p>
 <pre>
-  sudo apt-get install python3-dev
+  tar xzf QuantLib-SWIG-1.36.tar.gz
+</pre>
+This creates a folder <code>QuantLib-SWIG-1.36</code>;
+enter it and configure QuantLib by executing:
+<pre>
+  cd QuantLib-SWIG-1.36
+  ./configure
 </pre>
-<p>Similar packages should be available for most other
-distributions.</p>
 
-<p>Once you're done, you can try to run a few examples to check your
-installation. To do this, you can execute:</p>
+<p>After configuration, you can run
+<pre>
+  cd Python
+  make
+</pre>
+<p>This will create a binary wheel in the <code>dist</code> directory.
+To check that it works, run</p>
 <pre>
-  make -C Python check
+  make check
 </pre>
+<p>from the <code>Python</code> directory (you should already be there).</p>
+
+<p>Once you're done, you can take the wheel and install it
+with <code>pip</code> in the environment of your choice.</p>
 
 
 <h2>Installation from a git repository</h2>
@@ -122,10 +133,7 @@ get them by running</p>
 <p>After the execution of <code>./autogen.sh</code>, the installation
 proceeds as in the previous section. Note, though, that in this case
 you'll need SWIG available; you can download and install it
-from <a href="http://swig.org">http://swig.org</a> or, again, get it
-packaged for your distribution. On Ubuntu, for instance, the
-corresponding command would be</p>
-<pre>
-  sudo apt-get install swig
-</pre>
+from <a href="http://swig.org">http://swig.org</a>. At the time of
+this writing, the wrappers use SWIG 4.3.0.</p>
+
 

install/macosx-python.shtml

@@ -7,110 +7,134 @@ title: QuantLib-Python Installation on Mac OS X
 
 <h2>Installation from PyPI (recommended)</h2>
 
-<p>If you don't need to modify the wrappers, you might want to try
-installing a precompiled binary version.  The availability of binaries
-  depend on your operating system; to try to install them, run:</p>
+<p>If you don't need to modify the wrappers, you can install a
+precompiled wheel from PyPI.  Once you have activated the Python
+environment you want to use, make sure you have the latest version
+of <code>pip</code> by running:</p>
+<pre>
+  python -m pip install -U pip
+</pre>
+<p>(note that your Python interpreter might be named <code>python3</code> instead) and then run:</p>
 <pre>
   python -m pip install QuantLib
 </pre>
-<p>(If you have multiple versions of Python installed, run the above
-with the one you want to use QuantLib with.) If a binary package is
-available for your system, it will be installed and you will be able
-to leave this page and use it right away; if not, you'll have to
-compile it yourself as described in the next section.</p>
+<p>If a wheel is available for your system (which is likely)
+it will be installed and you will be able to leave this page and use
+it right away; if not, you'll have to compile it yourself as described
+in the next section.</p>
 
 <h2>Installation from a released version</h2>
 
 <p>The following assumes that you already installed
-QuantLib. Instructions for that are available
-at <a href="http://quantlib.org/install/macosx.shtml">http://quantlib.org/install/macosx.shtml</a>. In
-particular, check that you have provided the required options and
-environment variables to <tt>./configure</tt> and that you can execute
-the <tt>quantlib-config</tt> script.</p>
+QuantLib; instructions are available
+at <a href="http://quantlib.org/install/macosx.shtml">http://quantlib.org/install/macosx.shtml</a>.</p>
 
-<p>You can download released QuantLib-SWIG versions from GitHub
-at <a href="https://github.com/lballabio/QuantLib-SWIG/releases">https://github.com/lballabio/QuantLib-SWIG/releases</a>.</p>
+<h3>Setup</h3>
 
-<p>Once you have the tarball, extract it by executing:</p>
+<p>Before compiling the wrappers, you'll need to set up an appropriate
+environment:</p>
+<ul>
+  <li>Some of the commands you'll run will need to
+    invoke <code>quantlib-config</code> (which was installed with
+    QuantLib) to find out what flags should be passed to the compiler
+    and linker; they will also include the additional include
+    directories you might have specified when you built QuantLib, so
+    you'll be covered even if you have, say, Boost in a non-standard
+    place. This means that you must ensure
+    that <code>quantlib-config</code> is in your executable path.</li>
+  <li>You'll need to install a few Python modules.  It's good practice
+    to install them in a new virtual environment, to avoid possible
+    conflicts with your system Python installation.  This also helps
+    in case you have multiple versions of Python on your machine.  You
+    can create the virtual environment with
+<pre>
+  python3 -m venv .venv
+</pre>
+    and activate it with
 <pre>
-tar xzf QuantLib-SWIG-1.29.tar.gz
+  . .venv/bin/activate
 </pre>
-<p>(1.29 is the most recent version at the time of this writing; you
-might have downloaded another one, but take care to use one compatible
-with the version of QuantLib you installed.) This creates a
-folder <code>QuantLib-SWIG-1.29</code>; enter it and build QuantLib by
-executing the following commands.  For QuantLib 1.22 only, you will
-also need to add <tt>-std=c++11</tt> to <tt>CXXFLAGS</tt>.  Again,
-make sure that you can execute <tt>quantlib-config</tt> from the
-terminal, since the <tt>setup.py</tt> build will call it to retrieve a
-few required compilation flags.</p>
-<p><strong>On Mac OS X 10.11 (El Capitan) and later,</strong>
+    (mind the single dot at the beginning of the line.)  Once the
+    environment is active, run
+<pre>
+  pip install setuptools build tox pytest
+</pre>
+    If you're using <code>conda</code> to manage your environments,
+    you know what to do instead.
+  </li>
+  <li>You might have to set up a couple of environment variables:<br/>
+<strong>on Mac OS X 10.11 (El Capitan) and later,</strong>
 <pre>
-  cd QuantLib-SWIG-1.29/Python
   export CXXFLAGS='-O2 -stdlib=libc++ -mmacosx-version-min=10.9'
   export LDFLAGS='-stdlib=libc++ -mmacosx-version-min=10.9'
-  python3 setup.py build
 </pre>
-</p>
-<p><strong>On Mac OS X 10.9 (Mavericks) and 10.10 (Yosemite),</strong>
+<strong>on Mac OS X 10.9 (Mavericks) and 10.10 (Yosemite),</strong>
 <pre>
-  cd QuantLib-SWIG-1.29/Python
   export CXXFLAGS='-O2 -stdlib=libstdc++ -mmacosx-version-min=10.6'
   export LDFLAGS='-stdlib=libstdc++ -mmacosx-version-min=10.6'
-  python3 setup.py build
 </pre>
-</p>
-<p><strong>On earlier systems,</strong>
+<strong>on earlier systems,</strong>
 <pre>
-  cd QuantLib-SWIG-1.29/Python
   export CXXFLAGS='-O2'
-  python3 setup.py build
 </pre>
+  </li>
+  <li>Contrary to popular belief, working from a released
+    tarball <strong>doesn't require you to have SWIG
+    installed</strong>.</li>
+</ul>
+
+<h3>Compilation</h3>
+
+<p>You can download released QuantLib-SWIG versions from GitHub
+  at <a href="https://github.com/lballabio/QuantLib-SWIG/releases">https://github.com/lballabio/QuantLib-SWIG/releases</a>.
+  You should download the same version as the version of QuantLib you
+  installed; for the sake of example, I'll use version 1.36 which is
+  the most recent version at the time of this writing.
 </p>
 
-<p>Contrary to popular belief, working from a released
-tarball <strong>doesn't require you to have SWIG
-installed</strong>.  After building, you can run
+<p>Once you have the tarball, extract it by executing</p>
 <pre>
-  python3 setup.py install
+  tar xzf QuantLib-SWIG-1.36.tar.gz
 </pre>
-to perform a system installation; however, you might consider either passing an installation path, as in:
+This creates a folder <code>QuantLib-SWIG-1.36</code>;
+enter it and configure QuantLib by executing:
 <pre>
-  python3 setup.py install --prefix=/your/desired/location
+  cd QuantLib-SWIG-1.36
+  ./configure
 </pre>
-or building a wheel with
+
+<p>After configuration, you can run
 <pre>
-  python3 setup.py bdist_wheel
+  cd Python
+  make
 </pre>
-and use it for installation in the location you want; this will
-require the <tt>wheel</tt> package installed.</p>
-  
-<p>Also, note that simply calling
-<code>python3</code> as written above will find the first version of
-Python in your path.  If you want to use a different one (for instance
-because you installed multiple versions of Python, or you want to use
-an Anaconda installation) you must call your chosen Python
-interpreter; for instance, if you have Python 3.9 installed
-as <code>/Library/Frameworks/Python.framework/Versions/3.9/bin/python3</code>,
-you'll have to run:</p>
+<p>This will create a binary wheel in the <code>dist</code> directory.
+To check that it works, run</p>
 <pre>
-  CXXFLAGS='...' LDFLAGS='...' /Library/Frameworks/Python.framework/Versions/3.9/bin/python3 setup.py build
+  make check
 </pre>
+<p>from the <code>Python</code> directory (you should already be there).</p>
 
-<p>Once you're done, you can try to run a few examples to check your
-installation. To do this, you can execute:</p>
-<pre>
-  python3 setup.py test
-</pre>
+<p>Once you're done, you can take the wheel and install it
+with <code>pip</code> in the environment of your choice.</p>
 
 
 <h2>Installation from a git repository</h2>
 
 <p>If you want to compile from a checkout of a git repository (such as
 the official one
 at <a href="https://github.com/lballabio/quantlib-swig">https://github.com/lballabio/quantlib-swig</a>,
-or a fork of it that you might have created) you'll need SWIG
-available; you can download and install it
-from <a href="http://swig.org">http://swig.org</a> or, again, get it
-packaged from Homebrew or MacPorts.</p>
+or a fork of it that you might have created) you'll need an additional
+step at the beginning of the process. Before running
+the <code>./configure</code> script, you'll have to create it by
+executing</p>
+<pre>
+  ./autogen.sh
+</pre>
+<p>To do this, you'll need automake, autoconf and libtool; you can get them packaged from Homebrew or MacPorts.</p>
+<p>After the execution of <code>./autogen.sh</code>, the installation
+proceeds as in the previous section. Note, though, that in this case
+you'll need SWIG available; you can download and install it
+from <a href="http://swig.org">http://swig.org</a>. At the time of
+this writing, the wrappers use SWIG 4.3.0.</p>