From 272e7ce7201b8ebe5e8ddae8a9831be153d6369b Mon Sep 17 00:00:00 2001 From: q66 Date: Thu, 30 Mar 2017 01:08:51 +0200 Subject: [PATCH] move a lot of the README into documentation, write a nice main page --- README.md | 63 ++-------------------- doc/Doxyfile | 2 +- doc/main_page.md | 132 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 136 insertions(+), 61 deletions(-) create mode 100644 doc/main_page.md diff --git a/README.md b/README.md index ca5c45e..0b18ba0 100644 --- a/README.md +++ b/README.md @@ -11,63 +11,6 @@ make the language easier and more convenient to use. It is not feature complete right now, as most things are still being worked on. Documentation for OctaSTD can be found at https://docs.octaforge.org/octastd. - -## Supported compilers - -Compiler | Version --------- | ------- -gcc/g++ | 7+ -clang | 4+ - -You need those mainly to get the right standard library version (libstdc++ -or libc++). Other compilers might work as well, as long as the necessary -standard library features are supplied. - -MSVC++ is unsupported and for the time being will remain unsupported. As of MS -Visual Studio 2017 RC, basic C++11 features are still broken and prevent usage -of the library, with no reasonable workarounds. I will be testing new versions -as they get released and mark it supported as soon as it actually works, but no -active effort will be put towards making it work. On Windows, you're free to -use GCC/Clang, if you need Visual Studio, LLVM integration exists. - -## Why is C++17 necessary? - -Sadly, it's not possible to properly integrate `std::string` and `std::hash` -with OctaSTD ranges without utilizing `std::string_view`. Also, C++17 provides -library features that OctaSTD would have to implement otherwise, which would -lead to potentially incompatible APIs. C++17 also provides some nice language -features (such as `if constexpr` and fold expressions) which allow a lot of -code to be written in a cleaner way. However, it is made sure that no features -beyond the minimum supported compiler are necessary to use the library. - -## Supported operating systems and architectures - -OctaSTD targets POSIX compliant operating systems and Windows. Features are -written with those in mind, and other targets are currently not supported. - -Tier 1 targets are regularly tested. Tier 2 targets are irregularly tested. -Tier 3 targets are rarely or never tested, but most likely working and -accepting patches for. Unsupported targets may or may not work depending -on their POSIX compliance and ABI. - -| | Linux | FreeBSD | macOS | Windows | Other BSD | Solaris | AIX | Others | -|-----------------|:----------:|:-----------:|:----------:|:-----------:|:---------:|:--------:|:--------:|:------:| -| **x86** | **Tier 1** | **Tier 1** | Tier 2 | **Tier 1** | *Tier 3* | *Tier 3* | **No** | **No** | -| **x86_64** | **Tier 1** | **Tier 1** | **Tier 1** | **Tier 1** | *Tier 3* | *Tier 3* | **No** | **No** | -| **ARM/AArch64** | Tier 2 | Tier 2 | *Tier 3* | *Tier 3* | *Tier 3* | **No** | **No** | **No** | -| **MIPS32** | *Tier 3* | *Tier 3* | **No** | **No** | *Tier 3* | **No** | **No** | **No** | -| **PPC32/64** | *Tier 3* | *Tier 3* | **No** | **No** | *Tier 3* | **No** | *Tier 3* | **No** | -| **Others** | **No** | **No** | **No** | **No** | **No** | **No** | **No** | **No** | - -### Coroutines - -Coroutines use platform specific assembly code taken from Boost.Context. There -is assembly for all of the targets mentioned above. - -There is also support for stack allocators inspired again by the Boost.Context -library, with fixed size protected and unprotected allocators available on all -platforms, as well as a stack pool which allocates stacks in batches and -recycles dead stacks. - -Compile with the `OSTD_USE_VALGRIND` macro defined if you want useful Valgrind -output when using coroutines - this makes Valgrind aware of the custom stacks. +Please refer to it for further information (the main page should be answer +some more of your questions). You can also read `doc/main_page.md` and other +files in there directly if you don't need the API documentation. \ No newline at end of file diff --git a/doc/Doxyfile b/doc/Doxyfile index 4204740..5cab419 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -790,7 +790,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../ostd +INPUT = . ../ostd # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses diff --git a/doc/main_page.md b/doc/main_page.md new file mode 100644 index 0000000..ce983c8 --- /dev/null +++ b/doc/main_page.md @@ -0,0 +1,132 @@ +# OctaSTD Documentation {#index} + +## What is OctaSTD? + +OctaSTD is an extension library for C++17. It enhances the standard library +to make the language easier and more convenient to use. It's based on the +idea is that everything should do what one would expect it to; it strives +to aid programmers in writing clean and readable code. + +## The principles + +* It's time to drop the legacy. It creates unnecessary burden that gets in + the way of writing clean code. +* APIs should do mostly one thing and do it well. There's nothing worse than + things that have corner cases with strange semantics. +* If the standard library thing sucks, just replace it. +* At least attempt backwards compatibility and easy migration, but don't fear + dropping it if it gets in the way. + +## What does it provide? + +### Ranges + +OctaSTD started as a range library. Ranges replace iterators; you no longer +need two objects to represent a range and ranges themselves have a clean +interface that is easy to adapt for your own thing. Additionally, there is +backwards compatibility with iterators, so you can create ranges out of +iterator pairs and even turn a range into an iterator! However, the primary +way of creating ranges is using native range types. The compatibility stuff +is there mostly so that OctaSTD can work with existing libraries. Additionally, +a large library of generic range algorithms is provided. + +### Concurrency + +OctaSTD is a complete concurrency framework, implementing a clean and +extensible system for working with logical tasks. It allows for custom +schedulers and by default implements several scheduling approaches (1:1, +N:1, M:N). It also implements stackful coroutines (on which the latter +two schedulers are based) so you get full cooperative concurrency as +well as iterable generators. Safe synchronization and data transfer is +provided using Go-style channels and possibly other methods. Thanks to +all this, you can write scalable and safe applications that make proper +use of modern multicore machines. There is also a thread pool and other +utilities you might want to use in different places. + +### Streams + +There is a brand new I/O stream system to replace the aging and ugly iostreams +system from the standard library. Besides a much nicer interface, it's also +significantly more lightweight and intergrates with ranges! You can use +standard range algorithms to write into and read from files besides other +things. + +### Strings and formatting + +Thanks to ranges, OctaSTD provides very lightweight string slices. The +slices are not zero terminated, so creating sub-slices is fast and avoids +tons of potential heap allocations. None of the OctaSTD string APIs ever +assumes termination. + +Additionally, a completely type-safe string formatting system with C-like +format strings is provided. Thanks to being type-safe, you can do things +like using the `%s` format marks for any type and you never have to specify +sizes for numerical types. The system obviously integrates with ranges, so +you can format directly into any output range type. You can also implement +formatting for custom types, with complete control over the format mark. +All of this is zero-allocation, it lets the output range take care of that. + +### Others + +There are other APIs, too, including environment variable handling, simple +platform specific checks, a signal-slot event system or vector math. The +amount is expected to grow in the future, as OctaSTD is still a work in +progress. + +## Why C++17? + +C++17 includes several things that remove previous blockers, such as being +able to hash string range types sanely. Additionally, there are several +language features (such as `if constexpr`) that greatly simplify the code. +OctaSTD does not make full use of the standard, so it works with current +compilers. + +## Supported compilers + +Compiler | Version +-------- | ------- +gcc/g++ | 7+ +clang | 4+ + +You need those mainly to get the right standard library version (libstdc++ +or libc++). Other compilers might work as well, as long as the necessary +standard library features are supplied. + +MSVC++ is unsupported and for the time being will remain unsupported. As of MS +Visual Studio 2017 RC, basic C++11 features are still broken and prevent usage +of the library, with no reasonable workarounds. I will be testing new versions +as they get released and mark it supported as soon as it actually works, but no +active effort will be put towards making it work. On Windows, you're free to +use GCC/Clang, if you need Visual Studio, LLVM integration exists. + +## Supported operating systems and architectures + +OctaSTD targets POSIX compliant operating systems and Windows. Features are +written with those in mind, and other targets are currently not supported. + +Tier 1 targets are regularly tested. Tier 2 targets are irregularly tested. +Tier 3 targets are rarely or never tested, but most likely working and +accepting patches for. Unsupported targets may or may not work depending +on their POSIX compliance and ABI. + +| | Linux | FreeBSD | macOS | Windows | Other BSD | Solaris | AIX | Others | +|-----------------|:----------:|:-----------:|:----------:|:-----------:|:---------:|:--------:|:--------:|:------:| +| **x86** | **Tier 1** | **Tier 1** | Tier 2 | **Tier 1** | *Tier 3* | *Tier 3* | **No** | **No** | +| **x86_64** | **Tier 1** | **Tier 1** | **Tier 1** | **Tier 1** | *Tier 3* | *Tier 3* | **No** | **No** | +| **ARM/AArch64** | Tier 2 | Tier 2 | *Tier 3* | *Tier 3* | *Tier 3* | **No** | **No** | **No** | +| **MIPS32** | *Tier 3* | *Tier 3* | **No** | **No** | *Tier 3* | **No** | **No** | **No** | +| **PPC32/64** | *Tier 3* | *Tier 3* | **No** | **No** | *Tier 3* | **No** | *Tier 3* | **No** | +| **Others** | **No** | **No** | **No** | **No** | **No** | **No** | **No** | **No** | + +### Coroutines + +Coroutines use platform specific assembly code taken from Boost.Context. There +is assembly for all of the targets mentioned above. + +There is also support for stack allocators inspired again by the Boost.Context +library, with fixed size protected and unprotected allocators available on all +platforms, as well as a stack pool which allocates stacks in batches and +recycles dead stacks. + +Compile with the `OSTD_USE_VALGRIND` macro defined if you want useful Valgrind +output when using coroutines - this makes Valgrind aware of the custom stacks.