BUILDING.md

   1 ## Building (on Linux x86_64, with bash)
   2
   3 ### Python Environment
   4 First, make sure a virtual environment is set up with Cython and twine:
   5
   6 ```
   7 $ python -m venv .env
   8 $ source .env/bin/activate
   9 (.env) $ pip install --upgrade -r requirements.txt
  10 [...]
  11 (.env) $
  12 ```
  13
  14 ### Cython extensions
  15 Compile the Cython extensions to C:
  16
  17 ```
  18 (.env) $ cython sfpy/*.pyx
  19 (.env) $
  20 ```
  21
  22 ### Static libraries
  23 The extension module depends on the softposit and softfloat static libraries.
  24 They can be built with the following:
  25
  26 ```
  27 (.env) $ (cd SoftPosit/build/Linux-x86_64-GCC/; make clean; make)
  28 [...]
  29 (.env) $ (cd berkeley-softfloat-3/build/Linux-x86_64-GCC/; make clean; make)
  30 [...]
  31 (.env) $
  32 ```
  33
  34 Note that some changes are needed to the Makefiles so that the libraries are
  35 compiled with the correct options. Both libraries need to use -fPIC, and
  36 SoftPosit may need -std=c99 to work on older versions of GCC. See the
  37 diff below.
  38
  39 ### Building locally
  40 The extension modules can be built in place in the usual way:
  41
  42 ```
  43 (.env) $ python setup.py build_ext --inplace
  44 [...]
  45 (.env) $
  46 ```
  47
  48 A local wheel (compatible with the python version installed in the virtual
  49 environment) can be built with the following:
  50
  51 ```
  52 (.env) $ python setup.py bdist_wheel
  53 [...]
  54 (.env) $
  55 ```
  56
  57 The local wheel will be created in the `dist/` directory. This is the recommended
  58 way to install the package when building it from source locally:
  59
  60 ```
  61 $ pip install dist/sfpy*.whl
  62 [...]
  63 $ python
  64 >>> from sfpy import *
  65 >>> Posit8(1.3)
  66 Posit8(1.3125)
  67 >>>
  68 ```
  69
  70 ### Building manylinux1 wheels for distribution
  71 Widely compatible linux wheels can be built with the help of PyPA's manylinux
  72 docker image. This requires that Docker is installed, and that the host can pull
  73 the proper docker image.
  74
  75 To build the manylinux wheels, run:
  76
  77 ```
  78 $ sudo docker run -u $(id -u) --rm -v `pwd`:/io quay.io/pypa/manylinux1_x86_64 /io/docker-build-wheels.sh
  79 [...]
  80 $
  81 ```
  82
  83 This will create a set of manylinux1 wheel files in the `wheelhouse/` directory.
  84
  85 The docker build will make its own static libraries as part of the build process,
  86 and delete any existing static libraries with `make clean`.
  87
  88 The wheels can be uploaded to PyPI (if you're the package maintainer) with
  89
  90 ```
  91 (.env) $ twine upload --repository-url https://test.pypi.org/legacy/ wheelhouse/*
  92 [...]
  93 (.env) $
  94 ```
  95
  96 to test on test PyPI, or
  97
  98 ```
  99 (.env) $ twine upload wheelhouse/*
 100 [...]
 101 (.env) $
 102 ```
 103
 104 for a release.
 105
 106 ### Makefile customizations
 107 The Makefiles used to build the static libraries need a few small tweaks to
 108 make sure that all the right flags are given to gcc. The changes are shown
 109 in the following diffs.
 110
 111 `SoftPosit/build/Linux-x86_64/Makefile`
 112
 113 ```diff
 114 diff --git a/build/Linux-x86_64-GCC/Makefile b/build/Linux-x86_64-GCC/Makefile
 115 index 4409e43..46bb877 100644
 116 --- a/build/Linux-x86_64-GCC/Makefile
 117 +++ b/build/Linux-x86_64-GCC/Makefile
 118 @@ -60,9 +60,9 @@ LINK_PYTHON = \
 119
 120  DELETE = rm -f
 121  C_INCLUDES = -I. -I$(SOURCE_DIR)/$(SPECIALIZE_TYPE) -I$(SOURCE_DIR)/include
 122 -OPTIMISATION  = -march=core-avx2 -O2
 123 +OPTIMISATION  = -fPIC -O2 ^M
 124  COMPILE_C = \
 125 -  gcc -c -Werror-implicit-function-declaration -DSOFTPOSIT_FAST_INT64 \
 126 +  gcc -std=c99 -c -Werror-implicit-function-declaration -DSOFTPOSIT_FAST_INT64 \^M
 127      $(SOFTPOSIT_OPTS) $(C_INCLUDES) $(OPTIMISATION) \
 128      -o $@
 129  MAKELIB = ar crs $@
 130 ```
 131
 132 `berkeley-softfloat-3/build/Linux-x86_64/Makefile`
 133
 134 ```diff
 135 diff --git a/build/Linux-x86_64-GCC/Makefile b/build/Linux-x86_64-GCC/Makefile
 136 index 2ee5dad..b175964 100644
 137 --- a/build/Linux-x86_64-GCC/Makefile
 138 +++ b/build/Linux-x86_64-GCC/Makefile
 139 @@ -45,7 +45,7 @@ DELETE = rm -f
 140  C_INCLUDES = -I. -I$(SOURCE_DIR)/$(SPECIALIZE_TYPE) -I$(SOURCE_DIR)/include
 141  COMPILE_C = \
 142    gcc -c -Werror-implicit-function-declaration -DSOFTFLOAT_FAST_INT64 \
 143 -    $(SOFTFLOAT_OPTS) $(C_INCLUDES) -O2 -o $@
 144 +    $(SOFTFLOAT_OPTS) $(C_INCLUDES) -O2 -fPIC -o $@
 145  MAKELIB = ar crs $@
 146
 147  OBJ = .o
 148 ```