From 64b0911e01469224fa281491ee611f98ac4cef49 Mon Sep 17 00:00:00 2001 From: Alexander Lopez Date: Wed, 10 Jul 2024 22:18:05 -0700 Subject: [PATCH] add install rather than readme to release archive --- .github/workflows/release.yml | 2 +- INSTALL.md | 171 ++++++++++++++++++++++++++++++++++ README.md | 99 +++----------------- 3 files changed, 184 insertions(+), 88 deletions(-) create mode 100644 INSTALL.md diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 10306c5..eddd4c9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -19,7 +19,7 @@ jobs: - name: Create Release Zip run: | git rm -r --cached tests samples images res vcpkg etc .gitmodules .github - git rm --cached .clang-format .clang-tidy .pre-commit-config.yaml + git rm --cached .clang-format .clang-tidy .pre-commit-config.yaml README.md git archive $( git write-tree ) --format=zip --output=str_view-${GITHUB_REF#refs/tags/}.zip echo "ZIP_FILE=str_view-${GITHUB_REF#refs/tags/}.zip" >> $GITHUB_ENV diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 0000000..f4d2897 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,171 @@ +# Building and Installation + +## Quick Start + +Use the provided defaults, build the library, install the library, include the library. + +### Build the library + +Use GCC to compile the library. + +```zsh +make gcc-rel [OPTIONAL INSTALL PATH] +``` + +Use Clang to compile the library. + +```zsh +make clang-rel [OPTIONAL INSTALL PATH] +``` + +### Install the library + +By default, this library does not touch your system paths and it is installed in the `install/` directory of this folder. This is best for testing the library out while pointing `cmake` to the install location. Then, deleting the `install/` folder deletes any trace of this library from your system. + +```zsh +make install +``` +Then, in your `CMakeLists.txt`: + +```cmake +find_package(str_view HINTS "~/path/to/str_view-v[VERSION]/install") +``` + +If you want to simply write the following command in your `CMakeLists.txt`, + +```cmake +find_package(str_view) +``` + +specify that this library shall be installed to a location CMake recognizing by default. For example, my preferred location is as follows: + +```zsh +make gcc-rel ~/.local +make install +``` + +Then the installation looks like this. + +```txt +.local +├── include +│   └── str_view +│   └── str_view.h +└── lib + ├── cmake + │   └── str_view + │   ├── str_viewConfig.cmake + │   ├── str_viewConfigVersion.cmake + │   ├── str_viewTargets.cmake + │   └── str_viewTargets-release.cmake + └── str_view + └── libstr_view_release.a +``` + +Now to delete the library if needed, simply find all the `str_view` folders and delete them. You can also check the `build/install_manifest.txt` to confirm the locations of any files installed with this library. + +## Include the Library + +Once CMake can find the package, link against it and include the `str_view.h` header. + +The `CMakeLists.txt` file. + +```cmake +add_executable(my_exe my_exe.c) +target_link_libraries(my_exe str_view::str_view) +``` + +The C code. + +```.c +#include "str_view/str_view.h" +``` + +## Alternative Builds + +If you do not like the default presets, create a `CMakeUserPresets.json` in this folder and place your preferred configuration in that file. Here is my preferred configuration to get you started. I like to use a newer gcc version than the default presets specify. + +```json +{ + "version": 3, + "cmakeMinimumRequired": { + "major": 3, + "minor": 21, + "patch": 0 + }, + "configurePresets": [ + { + "name": "gdeb", + "displayName": "GMake GCC Debug", + "description": "Generated by GMake with GCC base debug preset.", + "generator": "Unix Makefiles", + "inherits": [ + "gcc-deb" + ], + "cacheVariables": { + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_C_STANDARD": "11", + "CMAKE_C_COMPILER": "gcc-12", + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_RUNTIME_OUTPUT_DIRECTORY": "${sourceDir}/build/deb", + "CMAKE_C_FLAGS": + "-g3 -Wall -Wextra -Wfloat-equal -Wtype-limits -Wpointer-arith -Wshadow -Winit-self -fno-diagnostics-show-option -Wno-nonnull-compare -Wno-pointer-bool-conversion" + } + }, + { + "name": "grel", + "displayName": "GMake GCC Release", + "description": "Generated by GMake with GCC base release preset.", + "generator": "Unix Makefiles", + "inherits": [ + "gcc-rel" + ], + "cacheVariables": { + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_C_STANDARD": "11", + "CMAKE_C_COMPILER": "gcc-12", + "CMAKE_BUILD_TYPE": "Release", + "CMAKE_RUNTIME_OUTPUT_DIRECTORY": "${sourceDir}/build/rel", + "CMAKE_C_FLAGS": + "-Wall -Wextra -Wfloat-equal -Wtype-limits -Wpointer-arith -Wshadow -Winit-self -fno-diagnostics-show-option -Wno-nonnull-compare -Wno-pointer-bool-conversion" + } + }, + { + "name": "cdeb", + "displayName": "Ninja clang Debug", + "description": "Generated by Ninja with clang base debug preset.", + "generator": "Ninja", + "inherits": [ + "clang-deb" + ], + "cacheVariables": { + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_C_STANDARD": "11", + "CMAKE_C_COMPILER": "clang", + "CMAKE_BUILD_TYPE": "Debug", + "CMAKE_RUNTIME_OUTPUT_DIRECTORY": "${sourceDir}/build/deb", + "CMAKE_C_FLAGS": + "-g3 -Wall -Wextra -Wfloat-equal -Wtype-limits -Wpointer-arith -Wshadow -Winit-self -fno-diagnostics-show-option -Wno-pointer-bool-conversion" + } + }, + { + "name": "crel", + "displayName": "Ninja clang Release", + "description": "Generated by Ninja with clang base release preset.", + "generator": "Ninja", + "inherits": [ + "clang-rel" + ], + "cacheVariables": { + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_C_STANDARD": "11", + "CMAKE_C_COMPILER": "clang", + "CMAKE_BUILD_TYPE": "Release", + "CMAKE_RUNTIME_OUTPUT_DIRECTORY": "${sourceDir}/build/rel", + "CMAKE_C_FLAGS": + "-Wall -Wextra -Wfloat-equal -Wtype-limits -Wpointer-arith -Wshadow -Winit-self -fno-diagnostics-show-option -Wno-pointer-bool-conversion" + } + } + ] +} +``` diff --git a/README.md b/README.md index d156c2b..af862f2 100644 --- a/README.md +++ b/README.md @@ -12,93 +12,18 @@ There are still improvements to be made to this library as time allows for packa ## Install Instructions -WIP +See [INSTALL.md](/INSTALL.md) for full build and installation instructions. -## Build Instructions +## Interface -Here is my sample user presets I prefer for developing the library locally. +Read the [`str_view.h`](/str_view/str_view.h) interface for the full API and documentation. -```cmake -{ - "version": 3, - "cmakeMinimumRequired": { - "major": 3, - "minor": 21, - "patch": 0 - }, - "configurePresets": [ - { - "name": "gdeb", - "displayName": "GMake GCC Debug", - "description": "Generated by GMake with GCC base debug preset.", - "generator": "Unix Makefiles", - "inherits": [ - "gcc-deb" - ], - "cacheVariables": { - "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", - "CMAKE_C_STANDARD": "11", - "CMAKE_C_COMPILER": "gcc-12", - "CMAKE_BUILD_TYPE": "Debug", - "CMAKE_RUNTIME_OUTPUT_DIRECTORY": "${sourceDir}/build/deb", - "CMAKE_C_FLAGS": - "-g3 -Wall -Wextra -Wfloat-equal -Wtype-limits -Wpointer-arith -Wshadow -Winit-self -fno-diagnostics-show-option -Wno-nonnull-compare -Wno-pointer-bool-conversion" - } - }, - { - "name": "grel", - "displayName": "GMake GCC Release", - "description": "Generated by GMake with GCC base release preset.", - "generator": "Unix Makefiles", - "inherits": [ - "gcc-rel" - ], - "cacheVariables": { - "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", - "CMAKE_C_STANDARD": "11", - "CMAKE_C_COMPILER": "gcc-12", - "CMAKE_BUILD_TYPE": "Release", - "CMAKE_RUNTIME_OUTPUT_DIRECTORY": "${sourceDir}/build/rel", - "CMAKE_C_FLAGS": - "-Wall -Wextra -Wfloat-equal -Wtype-limits -Wpointer-arith -Wshadow -Winit-self -fno-diagnostics-show-option -Wno-nonnull-compare -Wno-pointer-bool-conversion" - } - }, - { - "name": "cdeb", - "displayName": "Ninja clang Debug", - "description": "Generated by Ninja with clang base debug preset.", - "generator": "Ninja", - "inherits": [ - "clang-deb" - ], - "cacheVariables": { - "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", - "CMAKE_C_STANDARD": "11", - "CMAKE_C_COMPILER": "clang", - "CMAKE_BUILD_TYPE": "Debug", - "CMAKE_RUNTIME_OUTPUT_DIRECTORY": "${sourceDir}/build/deb", - "CMAKE_C_FLAGS": - "-g3 -Wall -Wextra -Wfloat-equal -Wtype-limits -Wpointer-arith -Wshadow -Winit-self -fno-diagnostics-show-option -Wno-pointer-bool-conversion" - } - }, - { - "name": "crel", - "displayName": "Ninja clang Release", - "description": "Generated by Ninja with clang base release preset.", - "generator": "Ninja", - "inherits": [ - "clang-rel" - ], - "cacheVariables": { - "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", - "CMAKE_C_STANDARD": "11", - "CMAKE_C_COMPILER": "clang", - "CMAKE_BUILD_TYPE": "Release", - "CMAKE_RUNTIME_OUTPUT_DIRECTORY": "${sourceDir}/build/rel", - "CMAKE_C_FLAGS": - "-Wall -Wextra -Wfloat-equal -Wtype-limits -Wpointer-arith -Wshadow -Winit-self -fno-diagnostics-show-option -Wno-pointer-bool-conversion" - } - } - ] -} -``` +## Status + +This library is not yet version `1.0`. To reach `1.0` I would like to implement the following. + +- More robust suite of tests to detect Undefined Behavor common with string handling. +- Better documentation highlighting when I cannot protect the user from Undefined Behavior through programmer error. +- SIMD intrinsics. At the very least, SIMD implemented for the short string brute force searches is critical. + +That being said, I have already found this library very helpful whenever I need to write C code. Please consider giving it a try.