README.md

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