Skip to content

Commit 93e021f

Browse files
crwilcoxcrwilcox
authored
docs: simplify main readme that is shown on pypi, add additional BUILDING.md (#54)
1 parent 1ba1235 commit 93e021f

File tree

2 files changed

+126
-140
lines changed

2 files changed

+126
-140
lines changed

‎BUILDING.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
2+
# Building
3+
4+
## Be sure to check out all submodules:
5+
6+
```
7+
$ git clone --recursive https://github.com/googleapis/python-crc32c
8+
```
9+
10+
## Building and Testing Wheels
11+
12+
The scripts directory contains multiple scripts for building. They are also
13+
used by the CI workflows which can be found at .github/workflows.
14+
15+
On Linux:
16+
17+
```
18+
./scripts/manylinux/build.sh
19+
20+
21+
# Install the wheel that was built as a result
22+
pip install cffi pycparser
23+
pip install --no-index --find-links=wheels google-crc32c
24+
25+
# Check the package, try and load the native library.
26+
python ./scripts/check_cffi_crc32c.py
27+
```
28+
29+
On OS X:
30+
31+
```
32+
# Build the C library and wheel
33+
./scripts/osx/build.sh
34+
35+
# Install the wheel that was built as a result
36+
pip install cffi pycparser
37+
pip install --no-index --find-links=wheels google-crc32c
38+
39+
# Check the package, try and load the native library.
40+
python ./scripts/check_cffi_crc32c.py
41+
```
42+
43+
On Windows:
44+
45+
```
46+
.\scripts\windows\build.bat
47+
.\scripts\windows\test.bat
48+
```
49+
50+
51+
## Installing locally for testing
52+
53+
Initialize the submodules and build the main `libcrc32c.so` shared
54+
library using `cmake` / `make`:
55+
56+
```bash
57+
$ cd python-crc32c
58+
$ git submodule update --init --recursive
59+
$ python -m venv venv
60+
$ venv/bin/pip install --upgrade setuptools pip wheel
61+
$ venv/bin/pip install cmake
62+
$ mkdir usr
63+
$ export CRC32C_INSTALL_PREFIX=$(pwd)/usr
64+
$ mkdir google_crc32c/build
65+
$ cd google_crc32c/build
66+
$ ../../venv/bin/cmake \
67+
> -DCRC32C_BUILD_TESTS=no \
68+
> -DCRC32C_BUILD_BENCHMARKS=no \
69+
> -DBUILD_SHARED_LIBS=yes \
70+
> -DCMAKE_INSTALL_PREFIX:PATH=${CRC32C_INSTALL_PREFIX} \
71+
> ..
72+
$ make all install
73+
$ cd ../..
74+
```
75+
76+
Now, run the tests:
77+
78+
```bash
79+
$ venv/bin/pip install -e .[testing]
80+
$ venv/bin/py.test tests/
81+
============================= test session starts ==============================
82+
platform linux -- Python 3.6.7, pytest-3.10.0, py-1.7.0, pluggy-0.8.0
83+
rootdir: ..., inifile:
84+
collected 9 items
85+
86+
tests/test___init__.py ......... [100%]
87+
88+
=========================== 9 passed in 0.03 seconds ===========================
89+
```

‎README.md‎

Lines changed: 37 additions & 140 deletions
Original file line numberDiff line numberDiff line change
@@ -6,143 +6,40 @@ are distributed as well as source. If a wheel is not published for the python
66
version and platform you are using, you will need to compile crc32c using a
77
C toolchain.
88

9-
10-
# Building
11-
12-
## Be sure to check out all submodules:
13-
14-
```
15-
$ git clone --recursive https://github.com/googleapis/python-crc32c
16-
```
17-
18-
## Prerequisites
19-
20-
On Linux:
21-
22-
- `docker`
23-
- `python3.7`
24-
25-
On OS X:
26-
27-
- `make`
28-
- [Official][1] `python.org` Python 2.7, 3.5, 3.6 and 3.7
29-
30-
On Windows:
31-
32-
- `cmake`
33-
- [Official][1] `python.org` Python 3.5, 3.6 and 3.7
34-
- Visual Studio 15 2017 (just the compiler toolchain)
35-
36-
Unfortunately, `libcrc32c` relies on many C++11 features, so
37-
building a Python 2.7 extension with the
38-
[Visual C++ Compiler for Python 2.7][2] is infeasible.
39-
40-
41-
## Building Wheels
42-
43-
On Linux:
44-
45-
```
46-
./scripts/manylinux/build.sh
47-
```
48-
49-
On OS X:
50-
51-
```
52-
./scripts/osx/build.sh
53-
```
54-
55-
On Windows: see `.appveyor.yml`.
56-
57-
## Testing/Verify Wheels
58-
59-
On Linux (i.e. a host OS, not a `docker` container):
60-
61-
```
62-
$ ./scripts/manylinux/check-37.sh
63-
...
64-
+ venv/bin/python check_cffi_crc32c.py
65-
_crc32c_cffi: <module 'crc32c._crc32c_cffi' from '.../python-crc32c/venv/lib/python3.7/site-packages/crc32c/_crc32c_cffi.abi3.so'>
66-
_crc32c_cffi.lib: <Lib object for 'crc32c._crc32c_cffi'>
67-
dir(_crc32c_cffi.lib): ['crc32c_extend', 'crc32c_value']
68-
+ unzip -l wheels/google_crc32c-0.0.1-cp37-cp37m-manylinux1_x86_64.whl
69-
Archive: wheels/google_crc32c-0.0.1-cp37-cp37m-manylinux1_x86_64.whl
70-
Length Date Time Name
71-
--------- ---------- ----- ----
72-
26120 2018-10-25 00:09 crc32c/_crc32c_cffi.abi3.so
73-
765 2018-10-24 23:57 crc32c/__init__.py
74-
29552 2018-10-25 00:09 crc32c/.libs/libcrc32c-f865a225.so
75-
109 2018-10-25 00:09 google_crc32c-0.0.1.dist-info/WHEEL
76-
766 2018-10-25 00:09 google_crc32c-0.0.1.dist-info/METADATA
77-
652 2018-10-25 00:09 google_crc32c-0.0.1.dist-info/RECORD
78-
1 2018-10-25 00:09 google_crc32c-0.0.1.dist-info/zip-safe
79-
7 2018-10-25 00:09 google_crc32c-0.0.1.dist-info/top_level.txt
80-
--------- -------
81-
57972 8 files
82-
...
83-
```
84-
85-
On OS X:
86-
87-
```
88-
$ ./scripts/osx/check.sh
89-
...
90-
+ venv37/bin/python .../python-crc32c/check_cffi_crc32c.py
91-
_crc32c_cffi: <module 'google_crc32c._crc32c_cffi' from '.../python-crc32c/venv37/lib/python3.7/site-packages/google_crc32c/_crc32c_cffi.abi3.so'>
92-
_crc32c_cffi.lib: <Lib object for 'google_crc32c._crc32c_cffi'>
93-
dir(_crc32c_cffi.lib): ['crc32c_extend', 'crc32c_value']
94-
+ /Library/Frameworks/Python.framework/Versions/3.7/bin/delocate-listdeps --all --depending .../python-crc32c/wheels/google_crc32c-0.0.1-cp37-cp37m-macosx_10_6_intel.whl
95-
/usr/lib/libSystem.B.dylib:
96-
google_crc32c/_crc32c_cffi.abi3.so
97-
google_crc32c/.dylibs/libcrc32c.dylib
98-
/usr/lib/libc++.1.dylib:
99-
google_crc32c/.dylibs/libcrc32c.dylib
100-
@loader_path/.dylibs/libcrc32c.dylib:
101-
google_crc32c/_crc32c_cffi.abi3.so
102-
...
103-
```
104-
105-
On Windows: TBD.
106-
107-
[1]: https://www.python.org/downloads/
108-
[2]: https://aka.ms/vcpython27
109-
110-
## Installing locally for testing
111-
112-
Initialize the submodules and build the main `libcrc32c.so` shared
113-
library using `cmake` / `make`:
114-
115-
```bash
116-
$ cd python-crc32c
117-
$ git submodule update --init --recursive
118-
$ python -m venv venv
119-
$ venv/bin/pip install --upgrade setuptools pip wheel
120-
$ venv/bin/pip install cmake
121-
$ mkdir usr
122-
$ export CRC32C_INSTALL_PREFIX=$(pwd)/usr
123-
$ mkdir google_crc32c/build
124-
$ cd google_crc32c/build
125-
$ ../../venv/bin/cmake \
126-
> -DCRC32C_BUILD_TESTS=no \
127-
> -DCRC32C_BUILD_BENCHMARKS=no \
128-
> -DBUILD_SHARED_LIBS=yes \
129-
> -DCMAKE_INSTALL_PREFIX:PATH=${CRC32C_INSTALL_PREFIX} \
130-
> ..
131-
$ make all install
132-
$ cd ../..
133-
```
134-
135-
Now, run the tests:
136-
137-
```bash
138-
$ venv/bin/pip install -e .[testing]
139-
$ venv/bin/py.test tests/
140-
============================= test session starts ==============================
141-
platform linux -- Python 3.6.7, pytest-3.10.0, py-1.7.0, pluggy-0.8.0
142-
rootdir: ..., inifile:
143-
collected 9 items
144-
145-
tests/test___init__.py ......... [100%]
146-
147-
=========================== 9 passed in 0.03 seconds ===========================
148-
```
9+
# Currently Published Wheels
10+
11+
Wheels are currently published for Python 3.6, 3.7, 3.8, 3.9 for multiple
12+
architectures. For information on building your own, please view [BUILDING.md](BUILDING.md).
13+
14+
## Linux
15+
Wheels are published for `manylinux1` and `manylinux2010` for `x86_64` architectures.
16+
17+
- google_crc32c-1.1.0-cp36-cp36m-manylinux1_x86_64.whl
18+
- google_crc32c-1.1.0-cp36-cp36m-manylinux2010_x86_64.whl
19+
- google_crc32c-1.1.0-cp37-cp37m-manylinux1_x86_64.whl
20+
- google_crc32c-1.1.0-cp37-cp37m-manylinux2010_x86_64.whl
21+
- google_crc32c-1.1.0-cp38-cp38-manylinux1_x86_64.whl
22+
- google_crc32c-1.1.0-cp38-cp38-manylinux2010_x86_64.whl
23+
- google_crc32c-1.1.0-cp39-cp39-manylinux1_x86_64.whl
24+
- google_crc32c-1.1.0-cp39-cp39-manylinux2010_x86_64.whl
25+
26+
27+
## Mac OS
28+
Wheels are published for `x86_64` architectures
29+
30+
- google_crc32c-1.1.0-cp36-cp36m-macosx_10_14_x86_64.whl
31+
- google_crc32c-1.1.0-cp37-cp37m-macosx_10_14_x86_64.whl
32+
- google_crc32c-1.1.0-cp38-cp38-macosx_10_14_x86_64.whl
33+
- google_crc32c-1.1.0-cp39-cp39-macosx_10_14_x86_64.whl
34+
35+
## Windows
36+
Wheels are published for `win32` and `win_amd64` architectures.
37+
38+
- google_crc32c-1.1.0-cp36-cp36m-win32.whl
39+
- google_crc32c-1.1.0-cp36-cp36m-win_amd64.whl
40+
- google_crc32c-1.1.0-cp37-cp37m-win32.whl
41+
- google_crc32c-1.1.0-cp37-cp37m-win_amd64.whl
42+
- google_crc32c-1.1.0-cp38-cp38-win32.whl
43+
- google_crc32c-1.1.0-cp38-cp38-win_amd64.whl
44+
- google_crc32c-1.1.0-cp39-cp39-win32.whl
45+
- google_crc32c-1.1.0-cp39-cp39-win_amd64.whl

0 commit comments

Comments
 (0)