github_mirrors/vectorscan
3
0
Fork 1
mirror of https://github.com/VectorCamp/vectorscan.git synced 2025-06-28 16:41:01 +03:00
Code Issues Packages Projects Releases Wiki Activity

more changes to readme

Browse Source
This commit is contained in:
Konstantinos Margaritis 2023-11-19 19:37:06 +02:00
parent a97d576ac8
commit 08b904b31c
1 changed files with 60 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
README.md
View File

@ -16,111 +16,20 @@ Pull Requests were made to the project for this reason. Unfortunately, the
PRs were rejected for now and the forseeable future, thus we have created Vectorscan for
our own multi-architectural and opensource collaborative needs.
The recent license change of Hyperscan makes Vectorscan even more needed.
The recent license change of Hyperscan makes Vectorscan even more relevant for the FLOSS ecosystem.
# What is Hyperscan?
# What is Vectorscan/Hyperscan/?
Hyperscan is a high-performance multiple regex matching library. It follows the
Hyperscan and by extension Vectorscan is a high-performance multiple regex matching library. It follows the
regular expression syntax of the commonly-used libpcre library, but is a
standalone library with its own C API.
Hyperscan uses hybrid automata techniques to allow simultaneous matching of
Hyperscan/Vectorscan uses hybrid automata techniques to allow simultaneous matching of
large numbers (up to tens of thousands) of regular expressions and for the
matching of regular expressions across streams of data.
Vectorscan is typically used in a DPI library stack, just like Hyperscan.
# Installation
## Debian/Ubuntu
On recent Debian/Ubuntu systems, vectorscan should be directly available for installation:
```
$ sudo apt install libvectorscan5
```
Or to install the devel package you can install `libvectorscan-dev` package:
```
$ sudo apt install libvectorscan-dev
```
## Fedora
TBD
## Suse
TBD
## Alpine
TBD
## Other
# Build Instructions
The build system has recently been refactored to be more modular and easier to extend. For that reason,
some small but necessary changes were made that might break compatibility with how Hyperscan was built.
## Common Dependencies
In order to build on Debian/Ubuntu make sure you install the following build-dependencies
```
$ sudo apt build-essential cmake ragel pkg-config libsqlite3-dev libpcap-dev
```
## Configure & build
In order to configure with `cmake` first create and cd into a build directory:
```
$ mkdir build
$ cd build
```
Then call `cmake` from inside the `build` directory:
```
$ cmake ../
```
Common options for Cmake are:
* `-DBUILD_STATIC_LIBS=On/Off` Build static libraries
* `-DBUILD_SHARED_LIBS=On/Off` Build shared libraries
* `-DCMAKE_BUILD_TYPE=[Release|Debug|RelWithDebInfo|MinSizeRel]` Configure build type and determine optimizations and certain features, for examples, Fat runtimes are not compatible with Debug mode at the moment.
And then you can run `make` in the same directory, if you have a multi-core system with `N` cores, running
```
$ make -j <N>
```
will speed up the process. If all goes well, you should have the vectorscan library
## Native CPU detection
Native CPU detection is off by default, however it is possible to build a performance-oriented non-fat library tuned to your CPU, as detected by the compiler:
```
$ cmake ../
```
## Instructions for Intel/AMD CPUs
## Instructions for Arm 64-bit CPUs
## Instructions for Power8/Power9/Power10 CPUs
## Fat Runtime (Intel/AMD 64-bit & Arm 64-bit Only)
# License
Vectorscan follows a BSD License like the original Hyperscan (up to 5.4).
@ -155,6 +64,84 @@ After careful consideration we decided that we will **NOT** aim to achieving com
If keeping up to date with latest API of Hyperscan, you should talk to Intel and get a license to use that.
However, we intend to extend Vectorscan's API with user requested changes or API extensions and improvements that we think are best for the project.
# Installation
## Debian/Ubuntu
On recent Debian/Ubuntu systems, vectorscan should be directly available for installation:
```
$ sudo apt install libvectorscan5
```
Or to install the devel package you can install `libvectorscan-dev` package:
```
$ sudo apt install libvectorscan-dev
```
For other distributions/OSes please check the [Wiki](https://github.com/VectorCamp/vectorscan/wiki/Installation-from-package)
# Build Instructions
The build system has recently been refactored to be more modular and easier to extend. For that reason,
some small but necessary changes were made that might break compatibility with how Hyperscan was built.
## Common Dependencies
In order to build on Debian/Ubuntu make sure you install the following build-dependencies
```
$ sudo apt build-essential cmake ragel pkg-config libsqlite3-dev libpcap-dev
```
## Configure & build
In order to configure with `cmake` first create and cd into a build directory:
```
$ mkdir build
$ cd build
```
Then call `cmake` from inside the `build` directory:
```
$ cmake ../
```
Common options for Cmake are:
* `-DBUILD_STATIC_LIBS=[On|Off]` Build static libraries
* `-DBUILD_SHARED_LIBS=[On|Off]` Build shared libraries (if none are set static libraries are built by default)
* `-DCMAKE_BUILD_TYPE=[Release|Debug|RelWithDebInfo|MinSizeRel]` Configure build type and determine optimizations and certain features.
* `-DUSE_CPU_NATIVE=[On|Off]` Native CPU detection is off by default, however it is possible to build a performance-oriented non-fat library tuned to your CPU
* `-DFAT_RUNTIME=[On|Off]` Fat Runtime is only available for X86 32-bit/64-bit and AArch64 architectures and only on Linux. It is incompatible with `Debug` type and `USE_CPU_NATIVE`.
### Specific options for X86 32-bit/64-bit (Intel/AMD) CPUs
* `-DBUILD_AVX2=[On|Off]` Enable code for AVX2.
* `-DBUILD_AVX512=[On|Off]` Enable code for AVX512. Implies `BUILD_AVX2`.
* `-DBUILD_AVX512VBMI=[On|Off]` Enable code for AVX512 with VBMI extension. Implies `BUILD_AVX512`.
### Specific options for Arm 64-bit CPUs
* `-DBUILD_SVE=[On|Off]` Enable code for SVE, like on AWS Graviton3 CPUs. Not much code is ported just for SVE , but enabling SVE code production, does improve code generation, see [Benchmarks](https://github.com/VectorCamp/vectorscan/wiki/Benchmarks).
* `-DBUILD_SVE2=[On|Off]` Enable code for SVE2, implies `BUILD_SVE`. Most non-Neon code is written for SVE2
* `-DBUILD_SVE2_BITPERM=[On|Off]` Enable code for SVE2_BITPERM harwdare feature, implies `BUILD_SVE2`.
## Build
If `cmake` has completed successfully you can run `make` in the same directory, if you have a multi-core system with `N` cores, running
```
$ make -j <N>
```
will speed up the process. If all goes well, you should have the vectorscan library compiled.
# Contributions
The official homepage for Vectorscan is at [www.github.com/VectorCamp/vectorscan](https://www.github.com/VectorCamp/vectorscan).