README.md (9043B)
1 # RSys 2 3 RSys is a library written in C89 defining several basic components 4 useful for developing C programs but not implemented in the standard C 5 library. Among other things, it provides macros describing the host 6 environment (OS, compiler, processor architecture, etc.), low-level 7 abstractions (thread, timer, ref counter, etc.), generic containers 8 (dynamic arrays, table of hashes, linked lists etc.) or even basic 9 linear algebra to manipulate vectors and matrices of dimensions 2, 3 or 10 4. 11 12 ## Requirements 13 14 - C compiler 15 - POSIX make 16 17 ## Installation 18 19 Edit config.mk as needed, then run: 20 21 make clean install 22 23 ## Release notes 24 25 ### Version 0.15 26 27 - Improve the building system. Simplify it by doing everything in one 28 place (the Makefile) and building all the tests in the same way. 29 Provide additional macros to control installation subdirectories. 30 - Remove (deprecated) support from Windows system and partial 31 (deprecated) support from macOS. The library now targets portability 32 of POSIX systems. 33 - Remove (deprecated) support from the CL compiler. 34 - Delete the code notified as obsolete for 8 years. 35 - Improve the portability of the endiannes functions by relying solely 36 on the C language and thus being independent of the order of bytes of 37 the machine, alignment, or anything else. 38 - Remove the OpenMP dependency. Only the tests used it. They now use 39 POSIX threads and therefore depend only on the C compiler. 40 41 ### Version 0.14 42 43 This version marks the replacement of CMake by Makefile as the build 44 system. The build procedure is written in POSIX make, which the user can 45 configure via the `config.mk` file. The POSIX script `make.sh` contains 46 commands that could be found directly in the Makefile, but which are 47 placed here to simplify its writing. 48 49 In addition to the features already provided by its CMake alternative, 50 the Makefile supports the construction of static libraries, provides an 51 uninstall target and updates compiler and linker flags to increase the 52 security and robustness of generated binaries. In any case, the main 53 motivation behind this writing is to use a good old well-established 54 standard with simple features, available on all UNIX systems, thus 55 simplifying its portability and support while being much lighter. 56 57 ### Version 0.13 58 59 - Complete rewrite of sha256 calculations. To compute a hash following 60 the sha256 cipher, we no longer rely on data pre-cut by the caller. As 61 in GnuPG or the GNU C library, sha256 calculations now use a context 62 that the caller updates with the data to digest. This rewrite 63 introduces an API break. 64 - Add `size_to_cstr` function: it fills a C string with human readable 65 text corresponding to a given size (in bytes). For example, 1024 can 66 be formatted as `1 KB` or `1024 B`, depending on the input arguments. 67 - Fix `time_dump` function: correct invalid memory write as well as 68 incorrect text formatting when write time is 0 and `TIME_DAY` flag is 69 set. 70 71 ### Version 0.12.1 72 73 - Fix compilation warnings with GCC 11. 74 - Fix the `text_reader` when the comment char is '\0'. 75 - Flush messages on default logger to force print them. 76 - License the project under the GPLv3+ license rather than the LGPLv3+ 77 license. 78 79 ### Version 0.12 80 81 - Add the `cstr_parse_list` function that parses a string as a tuple. 82 The function used to parse each element is defined by the caller. 83 - Add functions to encode/decode 2D and 3D morton indices. 84 - Add the `BIT_<U|I>16` macros that set a bit on a 16-bit integer. 85 - Add the FMADD macro defining wether the FMA instruction is supported 86 by the COMPILer. 87 - Fix the `time_dump` function: the returned `real_dump_size` was 88 wrongly evaluated. 89 90 ### Version 0.11 91 92 - Add the `find_iterator` function to the hash table data structure. 93 This function returns an iterator toward the hash table entry 94 corresponding to the submitted key. 95 - Increase the capacity of the "variadic macros" up to 9 arguments. 96 97 ### Version 0.10 98 99 - Add the `str_vprintf` and `str_append_[v]printf` functions to the 100 string API that sets the string content or appends text to it, 101 respectively. The input text is formatted following the `[v]printf` 102 syntax, i.e. a literal is used to format the text and a variable list 103 of data are either provided directly as function arguments (`printf`) 104 or through a `va_list` (`vprintf`). 105 - Add macros and functions to deal with data endianness. The 106 `BYTE_ORDER` macro defines the endianness of the host; its value can 107 be `LITTLE_ENDIAN` or `BIG_ENDIAN`. The `byte_swap_<16|32|64>` 108 functions revert the byte ordering of the submitted unsigned integer 109 of 16, 32 or 64 bits. Finally, the `<little|big>_endian_<16|32|64>` 110 functions ensure that the input unsigned integer follows the little or 111 big endian ordering: bytes are swapped only if the host endianness is 112 not the expected one. 113 - Add support of 256 bits hash. The `hash_sha256` function digest input 114 data wrt to the SHA-256 cryptographic hash algorithm. The 115 `hash256_to_cstr` function converts a 256 bits hash to its 116 corresponding lower case string. Finally The `hash256_eq` function 117 check that the submitted 256 bits hashes are the same. 118 119 ### Version 0.9.1 120 121 - Add the `VFATAL` macro that works as the regular `FATAL` macro but 122 with an additional variadic argument allowing to format the displayed 123 error message as in `printf`. 124 - Add the `str_printf` function to the string API: it sets the string 125 content with the data formatted wrt the `printf` syntax. 126 127 ### Version 0.9 128 129 - Add the text reader API. A text reader reads lines from a text stream. 130 In contrast to the `getline` POSIX function, a text reader skips the 131 empty lines as well as comments that are text directly following a 132 user defined comment character. 133 - Make silent the library API: the library functions do not print 134 anymore any message on the standard error. 135 136 ### Version 0.8.1 137 138 - Fix the allocation policy of the dynamic array that exhibited strong 139 performance issues when the `resize` function was used in a 140 `push_back` manner, i.e. to allocate a new entry at the end of the 141 dynamic array. 142 143 ### Version 0.8 144 145 - Update the allocation policy of the dynamic arrays: the `reserve` and 146 `resize` functions strictly allocate the submitted size if there is no 147 sufficient space already allocated. 148 - Add the `DARRAY_BUF` macro: give a direct access to the internal 149 buffer of the dynamic array. It is a less verbose alternative to the 150 `data_get` and `cdata_get` dynamic array functions that operate on 151 strongly typed data structures. 152 - Add the `d22_rotation` and `f22_rotation` functions: compute a 2x2 153 rotation matrix in the XY plane. 154 155 ### Version 0.7.1 156 157 - Add the FALLTHROUGH macro that disables compilation warning on switch 158 statement fallthrough. 159 - Fix a possible wrong return code in the set routine of the hash 160 tables. 161 162 ### Version 0.7 163 164 - Add the `res_to_cstr` function that returns a string describing the 165 submitted result code. 166 - Add the `SIMD_AVX` macro that is defined if the AVX instruction set is 167 available on the host machine. 168 - Fix the aligned allocation of the LIFO allocator: the returned address 169 was not necessarily aligned on the expected value. 170 - Fix the `search_lower_bound` algorithm. 171 - Fix a compilation error when RSys was linked against a version of the 172 GNU C Library less than 2.17. 173 174 ### Version 0.6.1 175 176 - Fix the detection of a 64-bits architecture on the CL compiler. 177 178 ### Version 0.6 179 180 - Remove the `big_buffer` container. Its implementation was awful and it 181 was thus useless. 182 - Add the read/write mutex API and provide an implementation with POSIX 183 threads. 184 - Add the `CHK` macro. It replaces the `[N]CHECK` macros that become 185 deprecated. 186 187 ### Version 0.5 188 189 - Add the `big_buffer` container, i.e. out of core dynamic array of POD 190 data. 191 - Update the `clock_time` API: the `time_<add|current|sub>` functions 192 return a pointer toward the result. 193 - Add the `time_zero` function that cleans-up the submitted time. 194 - Add a Last In First Out (LIFO) allocator. It uses a pre-allocated 195 memory pool to store a stack of allocated memory blocks. A memory 196 block is allocated on top of the stack. On "free" invocation, it is 197 marked as freed but it is effectively removed from the allocated 198 memory when it lies on top of the stack. 199 200 ### Version 0.4 201 202 - Add the `double2`, `double3`, `double4`, `double33`, `double22` and 203 `double44` data types that provide the same functionalities of their 204 `float` alternative. 205 - Add the `purge` function to the hash table and the dynamic array data 206 structures. This function not only resets the state of the structure, 207 as the `clear` function, but also frees its internal memory. 208 - Implement a new image API that provides and explicit image data 209 structure. The old API is still available but is deprecated. 210 211 ## License 212 213 Copyright © 2013-2023, 2025 Vincent Forest (vaplv@free.fr) 214 215 RSys is free software released under the GPL v3+ license: GNU GPL 216 version 3 or later. You are welcome to redistribute it under certain 217 conditions; refer to the COPYING files for details.