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 7affd4b..a7c792b 100644
 116 --- a/build/Linux-x86_64-GCC/Makefile
 117 +++ b/build/Linux-x86_64-GCC/Makefile
 118 @@ -42,7 +42,7 @@
 119  SOURCE_DIR ?= ../../source
 120  PYTHON_DIR ?= ../../python
 121  SPECIALIZE_TYPE ?= 8086-SSE
 122 -COMPILER ?= gcc
 123 +COMPILER ?= gcc -std=c11^M
 124
 125  SOFTPOSIT_OPTS ?= \
 126    -DINLINE_LEVEL=5 #\
 127 @@ -69,7 +69,7 @@ endif
 128  C_INCLUDES = -I. -I$(SOURCE_DIR)/$(SPECIALIZE_TYPE) -I$(SOURCE_DIR)/include
 129  OPTIMISATION  = -O2 #-march=core-avx2
 130  COMPILE_C = \
 131 -  $(COMPILER) -c -Werror-implicit-function-declaration -DSOFTPOSIT_FAST_INT64 \
 132 +  $(COMPILER) -fPIC -c -Werror-implicit-function-declaration -DSOFTPOSIT_FAST_INT64 \^M
 133      $(SOFTPOSIT_OPTS) $(C_INCLUDES) $(OPTIMISATION) \
 134      -o $@
 135  MAKELIB = ar crs $@
 136 ```
 137
 138 `berkeley-softfloat-3/build/Linux-x86_64/Makefile`
 139
 140 ```diff
 141 diff --git a/build/Linux-x86_64-GCC/Makefile b/build/Linux-x86_64-GCC/Makefile
 142 index 2ee5dad..b175964 100644
 143 --- a/build/Linux-x86_64-GCC/Makefile
 144 +++ b/build/Linux-x86_64-GCC/Makefile
 145 @@ -45,7 +45,7 @@ DELETE = rm -f
 146  C_INCLUDES = -I. -I$(SOURCE_DIR)/$(SPECIALIZE_TYPE) -I$(SOURCE_DIR)/include
 147  COMPILE_C = \
 148    gcc -c -Werror-implicit-function-declaration -DSOFTFLOAT_FAST_INT64 \
 149 -    $(SOFTFLOAT_OPTS) $(C_INCLUDES) -O2 -o $@
 150 +    $(SOFTFLOAT_OPTS) $(C_INCLUDES) -O2 -fPIC -o $@
 151  MAKELIB = ar crs $@
 152
 153  OBJ = .o
 154 ```