Unix-like systems

To install from source, type “python setup.py install” in the source’s directory (where setup.py is located).

Alternatively a package manager such as pip can be used (pip install ntracer) to download, build and install this package in one step.

Windows

To compile with the default windows compiler (Microsoft Visual C++), you need at least the 2019 version. However, the 2019 version (the latest version at the time of this writing) produces a significantly slower binary. To compile with MSVC anyway, follow the steps described in “Unix-like systems” above.

The recommended way to compile is with MinGW-w64 (MinGW32 lacks the needed C++ thread library). Despite the name, it doesn’t require a 64-bit version of Windows. It doesn’t matter how Python itself was compiled.

To build with MinGW-w64, execute the following commands in the package source directory (where setup.py is located):

set PATH=<base path of MinGW-w64>\bin;%PATH%
<Python install directory>\python.exe setup.py build --compiler=mingw32 install

By default, the build command will also copy any MinGW-w64 DLLs that the binaries require into the installation directory (technically it only copies the DLLs into the temporary build directory and the install command does the installing). To suppress this behaviour (which you may want to do if the MinGW-w64 bin directory is already in the system-wide path), use the build flag --copy-mingw-deps=false.

Customization

When compiling under GCC or Clang, the setup script will use the -march=native parameter to use the most recent instruction set that the current CPU supports. To override this or for any other customization, the build command supports the flag --cpp-opts=<options> which will add the specified options to the end of the argument list when invoking the compiler. There is also the flag --ld-opts=<options> for adding linker options. To remove arguments that lack a negative form, you can use --cpp-neg-opts=<options> and --ld-neg-opts=<options>, where options is a space-separated list of strings that will be removed from the list of compiler and linker options respectively.

MSVC lacks an equivalent to -march=native and also has less fined-grained control over SSE/AVX options. Thus, when building with MSVC, a small program is first built, that checks the capabilities of the current CPU. This can be suppressed by adding --test-cpu-flags=false to the build command.

For controlling the SSE/AVX instructions used, the compiler’s /arch flag can be used (e.g. --cpp-opts=/arch:AVX512), but for finer grained control, any of the following macros may be also defined:

• SUPPORT_SSE

• SUPPORT_SSE2

• SUPPORT_SSE3

• SUPPORT_SSSE3

• SUPPORT_SSE4_1

• SUPPORT_SSE4_2

• SUPPORT_AVX

• SUPPORT_AVX2

• SUPPORT_AVX512F

where each one of these implies all of macros above it.

The following can also be defined:

• SUPPORT_AVX512BW

• SUPPORT_AVX512CD

• SUPPORT_AVX512DQ

• SUPPORT_AVX512ER

• SUPPORT_AVX512PF

• SUPPORT_AVX512VL

which are independent of each other. Note that not all of these instruction sets will necessarily be used, but they are still available for future compatibility.

Even when using these macros, the /arch flag should still be used for maximum benefit. E.g. for 32-bit systems: --cpp-opts="/arch:SSE2 /DSUPPORT_SSE4_1" (the /arch:SSE2 option is not present for 64-bit systems because x86-64 always supports SSE2).

These macros can also be defined for GCC/Clang, but those compilers have flags for each of these instruction sets already.

Building Documentation

Note that you must first build the package and it must be made importable (either by installing it or by setting the PYTHONPATH environment variable to where it was built), because some of the documentation is pulled from the doc-strings.

To generate the documentation, run python setup.py build_sphinx. Sphinx, LaTex and dvipng are required.