Skip to content

Commit

Permalink
docs: update readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@Curve
Curve committed Dec 6, 2023
1 parent d60401d commit d96229b
Showing 1 changed file with 37 additions and 53 deletions.
90 changes: 37 additions & 53 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,28 +1,35 @@
# ViennaLS
<div align="center">

# <img src="assets/logo.png" height="30"> ViennaLS

[![Linux](https://github.com/ViennaTools/ViennaLS/actions/workflows/linux_test.yml/badge.svg)](https://github.com/ViennaTools/ViennaLS/actions/workflows/linux_test.yml)
[![macOS](https://github.com/ViennaTools/ViennaLS/actions/workflows/macos_test.yml/badge.svg)](https://github.com/ViennaTools/ViennaLS/actions/workflows/macos_test.yml)
[![Windows](https://github.com/ViennaTools/ViennaLS/actions/workflows/windows_test.yml/badge.svg)](https://github.com/ViennaTools/ViennaLS/actions/workflows/windows_test.yml)

</div>

ViennaLS is a header-only C++ level set library developed for high performance topography simulations. The main design goals are simplicity and efficiency, tailored towards scientific simulations. ViennaLS can also be used for visualisation applications, although this is not the main design target.

IMPORTANT NOTE: ViennaLS is under heavy development and improved daily. If you do have suggestions or find bugs, please let us know!
> [!NOTE]
> ViennaLS is under heavy development and improved daily. If you do have suggestions or find bugs, please let us know!
## Support

[Documentation](https://viennatools.github.io/ViennaLS/doxygen/html/index.html) and [Examples](https://viennatools.github.io/ViennaLS/doxygen/html/examples.html) can be found online.
[Documentation](https://viennatools.github.io/ViennaLS/index.html) and [Examples](./Examples/) can be found online.

Bug reports and suggestions should be filed on GitHub.

## Releases

Releases are tagged on the maser branch and available in the [releases section](https://github.com/ViennaTools/ViennaLS/releases).

## Building

### Supported Operating Systems

* Windows (Visual Studio)
* Windows (MSVC)

* Linux (g++ / clang)
* Linux (g++ & clang)

* macOS (XCode)

Expand All @@ -31,7 +38,9 @@ Releases are tagged on the maser branch and available in the [releases section](

* C++17 Compiler with OpenMP support

### Dependencies (installed automatically)
### Dependencies

> Dependencies will be installed automatically when not available.
* [ViennaHRLE](https://github.com/ViennaTools/ViennaHRLE)

Expand Down Expand Up @@ -72,20 +81,12 @@ cmake --build build

## Installing with dependencies already installed on the system

The CMake configuration automatically checks if the dependencies are installed. If CMake is unable to find them, the dependencies will be built from source with the _buildDependencies_ target.

```bash
git clone https://github.com/ViennaTools/ViennaLS.git
cd ViennaLS

cmake -B build -DCMAKE_INSTALL_PREFIX=/path/to/your/custom/install/
cmake --build build
```
If one wants to use a specific installation of one or more of the dependencies, just pass the corresponding _*_DIR_ variable as a configuration option (e.g. -DVTK_DIR=/path/to/vtk/install -Dpybind11_DIR=/path/to/pybind11 -DViennaHRLE_DIR=/path/to/viennahrle)
The CMake configuration automatically checks if the dependencies are installed. If CMake is unable to find them, the dependencies will be built from source.

## Building the Python package

> __Tip__: On systems that feature a package manager (e.g. Ubuntu/Debian `apt`), the dependencies can be installed beforehand (e.g. using ```sudo apt install libvtk9.1 libvtk9-dev pybind11-dev```), which saves a considerable amount of time during compilation.
> [!NOTE]
> On systems that feature a package manager (e.g. Ubuntu/Debian `apt`), the dependencies can be installed beforehand (e.g. using ```sudo apt install libvtk9.1 libvtk9-dev pybind11-dev```), which saves a considerable amount of time during compilation.
The Python package can be built and installed using the `pip` command:

Expand All @@ -108,23 +109,6 @@ In order to switch to three dimensions, only the import needs to be changed:
import viennals3d as vls
```

## Setting up the dependencies

If you just want to install all dependencies before doing anything else, run:

```bash
git clone https://github.com/ViennaTools/ViennaLS.git
cd ViennaLS
mkdir build && cd build
cmake .. -DCMAKE_INSTALL_PREFIX=/path/to/your/custom/install/
make pybind11_external
make viennahrle_external
make vtk_external
```

This will take some time the first time it is run.
The dependencies only need to be set up once.

## Running the Tests

ViennaLS uses CTest to run its tests.
Expand All @@ -136,7 +120,7 @@ cd ViennaLS

cmake -B build -DVIENNALS_BUILD_TESTS=ON
cmake --build build
ctest -E "Benchmark|Performance" --test-dir build
ctest -E "Benchmark|Performance" --test-dir build
```

## Building examples
Expand All @@ -150,34 +134,34 @@ cmake --build build

## Integration in CMake projects

In order to use this library in your CMake project, add the following lines to the CMakeLists.txt of your project:
We recommend using [CPM.cmake](https://github.com/cpm-cmake/CPM.cmake) to consume this library.

```cmake
set(ViennaLS_DIR "/path/to/your/custom/install/")
find_package(ViennaLS REQUIRED PATHS ${ViennaLS_DIR})
add_executable(myExe mySource.cpp)
target_include_directories(myExe PUBLIC ${VIENNALS_INCLUDE_DIRS})
target_link_libraries(myExe ${VIENNALS_LIBRARIES})
```
* Installation with CPM
```cmake
CPMAddPackage("gh:viennatools/[email protected]")
```

* With a local installation
> In case you have ViennaLS installed in a custom directory, make sure to properly specify the `CMAKE_MODULE_PATH`
```cmake
find_package(ViennaLS REQUIRED)
target_link_libraries(${PROJECT_NAME} ViennaTools::ViennaLS)
```
### Shared libraries
### Shared Library
In order to save build time during development, dynamically linked shared libraries can be used
if ViennaLS was built with them. This is done by precompiling the most common template specialisations.
In order to use shared libraries, use
```bash
cmake .. -DVIENNALS_PRECOMPILE_HEADERS=ON
```
If ViennaLS was built with shared libraries and you use ViennaLS in your project (see above), CMake will automatically link them to your project. In order to build a release of your own project with better runtime performance, but
longer build times, use the following CMake option when building a release:
```bash
VIENNALS_USE_PRECOMPILED=OFF
cmake -B build -DVIENNALS_PRECOMPILE_HEADERS=ON
```
If ViennaLS was built with shared libraries and you use ViennaLS in your project (see above), CMake will automatically link them to your project.

## Contributing
Before being able to merge your PR, make sure you have met all points on the checklist in [CONTRIBUTING.md](https://github.com/ViennaTools/viennals/blob/master/CONTRIBUTING.md).

If you want to contribute to ViennaLS, make sure to follow the [LLVM Coding guidelines](https://llvm.org/docs/CodingStandards.html). Before creating a pull request, make sure ALL files have been formatted by clang-format, which can be done using the format-project.sh script in the root directory.
If you want to contribute to ViennaLS, make sure to follow the [LLVM Coding guidelines](https://llvm.org/docs/CodingStandards.html). Before creating a pull request, make sure ALL files have been formatted by clang-format, which can be done using the `format-project.sh` script in the root directory.

## Authors

Expand All @@ -190,6 +174,6 @@ Contact us via: [email protected]
ViennaLS was developed under the aegis of the 'Institute for Microelectronics' at the 'TU Wien'.
http://www.iue.tuwien.ac.at/

License
--------------------------
## License

See file LICENSE in the base directory.

0 comments on commit d96229b

Please sign in to comment.