abdelrahman/wizapp-stdlib
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Update homepage

Abdelrahman Said
2026-03-09 22:05:20 +00:00
parent e6100f9bb2
commit 5d184f91a5
1 changed files with 94 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files

162
Home.md

@@ -1,112 +1,138 @@
# Wizard Apprentice Standard Library # Wizard Apprentice Standard Library
The Wizard's Apprentice Standard Library (`wapp` for short) is a collection of C/C++ utilities that are meant as a replacement to several parts of the standard libraries of both these languages. It's mostly a C11 library with some C++11 functionality used when necessary. The Wizard's Apprentice Standard Library (`wapp` for short) is a collection of C/C++ utilities intended to replace several parts of the standard libraries of both languages. It is primarily written as a C11 library, with some C++11 functionality used where necessary.
## Building ## Usage
The library is mainly developed on Linux/macOS, so it uses `make` for building the code. However, it mostly uses it as a task runner rather than a full fledged build system. It also is designed to work without even needing a build system so it can be added to a codebase and used as is. `wapp` is distributed as a source library, meaning it can be used directly in your codebase without building the library beforehand or relying on a specific build system. Each package exposes its interface through a single header file and a single source file, and the same approach applies to the library as a whole.
Clone the repo to your computer. To start using the library, download the latest [release](https://git.thewizardapprentice.com/abdelrahman/wizapp-stdlib/releases).
```bash There are three ways to use the library, listed from the simplest to the most advanced.
git clone https://git.thewizardapprentice.com/abdelrahman/wizapp-stdlib.git
cd wizapp-stdlib
```
To build the library and run the tests, simply run ### 1) Use the whole library
```bash Include the `wapp.h` file wherever you want to use the library and add the `wapp.c` file to your build step.
./build
```
For more info on the available variables and targets, run ### 2) Use a single package from the library
```bash Each package provides its own header and source files. For example, the `base` package provides `wapp_base.h` and `wapp_base.c`. Including the header and adding the corresponding source file to your build step enables that package in your project.
make help
```
On Windows, you can run the `build.ps1` script in PowerShell. This will also build the library using Microsoft's `msvc` compiler and run the tests. However, this PowerShell script isn't at feature parity yet with the available `Makefile`. ### 3) Using multiple packages
While this might seem as a limitation, the library is basically structured so you don't even need any build system. Both the `Makefile` and the `build.ps1` script are mostly meant to be used for development purposes rather than necessarily This approach is slightly more advanced. If you want to use multiple packages, consult the documentation for the packages you are interested in. Some packages depend on others, and those dependencies are already included internally.
If you manually add multiple dependent source files to your build step, compilation may fail because it violates the [One Definition Rule](https://en.wikipedia.org/wiki/One_Definition_Rule).
Each package's documentation lists its dependencies so you can include them correctly.
### Build Macros ### Build Macros
When using the library without the build scripts, there are a couple of macros that you might want to consider defining: When using the library without the provided build scripts, you may want to define the following macros:
- `WAPP_DEBUG_ASSERT` -> Enables some extra checks for debug builds. It's highly encouraged to define this macro when developing with the library to catch any mistakes. - `WAPP_DEBUG_ASSERT` → Enables additional debug checks. It is strongly recommended to define this during development to help catch mistakes early.
- `WAPP_NO_RUNTIME_ASSERT` -> Disables all runtime safety checks. Ideally, this macro should ***NEVER*** be used. However, if you are absolutely confident and would like to skip all safety checks at runtime, feel free to define it. - `WAPP_NO_RUNTIME_ASSERT` → Disables all runtime safety checks. This macro should ideally never be used. However, if you are absolutely confident and want to remove runtime safety checks for performance reasons, you may define it.
## Packages
To learn more about the different packages in the library, refer to the packages documentation (`Packages.md`).
## Library Structure ## Library Structure
The `src` directory of the library has the following structure The `src` directory of the library has the following structure:
``` ```
src/ src/
├── base ├── base
│   ├── array │ ├── array
│   ├── dbl_list │ ├── dbl_list
│   ├── mem │ ├── mem
│   │   ├── allocator │ │ ├── allocator
│   │   └── utils │ │ └── utils
│   ├── queue │ ├── queue
│   └── strings │ └── strings
│   └── str8 │ └── str8
├── common ├── common
│   ├── aliases │ ├── aliases
│   ├── assert │ ├── assert
│   ├── misc │ ├── misc
│   └── platform │ └── platform
├── os ├── os
│   ├── allocators │ ├── allocators
│   │   └── arena │ │ └── arena
│   ├── cpath │ ├── cpath
│   ├── file │ ├── file
│   │   ├── posix │ │ ├── posix
│   │   └── win │ │ └── win
│   ├── mem │ ├── mem
│   │   ├── posix │ │ ├── posix
│   │   └── win │ │ └── win
│   └── shell │ └── shell
│   ├── commander │ ├── commander
│   │   ├── posix │ │ ├── posix
│   │   └── win │ │ └── win
│   ├── termcolour │ ├── termcolour
│   │   ├── posix │ │ ├── posix
│   │   └── win │ │ └── win
│   └── utils │ └── utils
├── prng ├── prng
│   └── xorshift │ └── xorshift
├── testing ├── testing
│   └── tester │ └── tester
└── uuid └── uuid
``` ```
Each subdirectory living directly under the `src` directory acts as a self contained package. Some of these packages depend on other packages in the library, however, there is no need to know anything about these dependencies. The library relies on relative includes to ensure that all dependencies are resolved correctly. Each package comes with one header file and one source file that include all the dependencies. Each subdirectory directly under `src` acts as a self-contained package. Some packages depend on others within the library, but these dependencies are handled internally through relative includes. As a result, users generally do not need to manage dependencies manually.
Each package provides a single header file and a single source file that include everything required for that package.
``` ```
src/ src/
├── base ├── base
│   ├── wapp_base.c │ ├── wapp_base.c
│   └── wapp_base.h │ └── wapp_base.h
├── common ├── common
│   └── wapp_common.h │ └── wapp_common.h
├── os ├── os
│   ├── wapp_os.c │ ├── wapp_os.c
│   └── wapp_os.h │ └── wapp_os.h
├── prng ├── prng
│   ├── wapp_prng.c │ ├── wapp_prng.c
│   ├── wapp_prng.h │ ├── wapp_prng.h
├── testing ├── testing
│   ├── wapp_testing.c │ ├── wapp_testing.c
│   └── wapp_testing.h │ └── wapp_testing.h
├── uuid ├── uuid
│   ├── wapp_uuid.c │ ├── wapp_uuid.c
│   └── wapp_uuid.h │ └── wapp_uuid.h
├── wapp.c ├── wapp.c
└── wapp.h └── wapp.h
``` ```
You can basically include the header file and use the source file and you would effectively be using that package. This also applies to the full library. If you include `wapp.h` and add `wapp.c` as part of your build step, you would be effectively using the whole library. This way, you don't even need to use any build systems. To use a package, simply include its header file and add the corresponding source file to your build step. The same principle applies to the full library: include `wapp.h` and add `wapp.c` to your build step to use the entire library.
## Packages ## Building
To learn more about the different packages of the library, please refer to the [packages](Packages.md) section. This section is only relevant if you want to contribute to or develop the library itself. The build scripts both compile the library and run the C and C++ test suites.
The library is primarily developed on Linux and macOS, so it uses `make` to build the code. However, it functions mostly as a task runner rather than a full build system.
Clone the repository:
``` bash
git clone https://git.thewizardapprentice.com/abdelrahman/wizapp-stdlib.git
cd wizapp-stdlib
```
To build the library and run the tests:
``` bash
./build
```
For more information about available variables and targets:
``` bash
make help
```
On Windows, you can run the `build.ps1` script in PowerShell. This script builds the library using Microsoft's `msvc` compiler and runs the tests. While it does not yet provide full feature parity with the `Makefile`, it performs the necessary steps (building and testing) to verify that the library works correctly on Windows.