From 2b29af8697f6d859f0a3c5ec9dceac0e4fded3af Mon Sep 17 00:00:00 2001 From: checkroom Date: Thu, 21 Nov 2024 11:56:59 +0000 Subject: [PATCH] [skip ci] Improving docs --- docs/for-developers.md | 52 ++++++++++++++++++++++++++---------------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/docs/for-developers.md b/docs/for-developers.md index b8c7e5c0..06bddb7d 100644 --- a/docs/for-developers.md +++ b/docs/for-developers.md @@ -44,7 +44,7 @@ This is just temporary limitation, as all dependencies are portable, but my own ## Building process > [!NOTICE] -> This project uses meson, so there are no git submodules for the most part. +> This project uses meson, so there are no git submodules for the most part. > One exception is made for `flatpak-builder` to be usable. > If you plan on using it to generate new flatpak images, please ensure submodules are also cloned with the rest of the repository. @@ -141,6 +141,32 @@ In either case, such files are not tracked by git. They are frequently used for both _benchmarks_ and _tests_. They can also be useful for the developer while testing new functionality, so they have been all covered in [here](./env-vars.md) for reference. +## Logging + +### Debug logging + +**vs** has some features to simplify debugging, mostly to support automatic tests and benchmarks, but they might be useful in other scenarios as well. +`vs::globals::debug` is responsible for that, and it is exposed in several ways: + +- within embedded scripts +- via a special xml `debug` tag +- in the `vs.fltk` C interface as well + While using it you can define a key and value. The current timestamp at nanoseconds resolution is also automatically recorded. + Records are saved to a file with name `VS_DEBUG_FILE` if set, otherwise no output will be emitted. Older content is destroyed. + The file format is just a simple CSV with horizontal tabs as separator of fields and newlines for rows. The order is _key_, _value_ & _timestamp_. + +`vs::globals::debug` should not be confused with the ordinary logging functions which are also exposed in similar ways, but which are generally contextual and they mostly output to `stdout`. + +## Testing & Benchmarking + +### Testing features of the vs-fltk library + +### Memory profile of vs + +### Benchmarking features of the vs-fltk library + +### Runtime tests in vs + ## Programming guidelines ### About exceptions @@ -157,44 +183,30 @@ As for memory allocations, spawning small dynamic objects is also discouraged. I ### About log levels Internally these are the log levels supported and their relative semantics: + - **INFO** to present informational messages, often as a result of user requests - **OK** to notify that a certain operation completed successfully. -- **WARNING** to notify that a certain operation was not able to fully succeed, something should be fixed, but everything is fine. +- **WARNING** to notify that a certain operation was not able to fully succeed, something should be fixed, but everything is fine. - **CONTINUE** to notify that a certain operation was skipped by design. - **PANIC** to notify that a certain operation failed in a way which cannot be recovered (but the application can still run) - **LOG** to introduce a log without any further connotation. For example, loading a remote resource: + - If the file was already cached, a `continue` message will be notified - If no proper answer has been received from the remote host, a `panic` message is generated, since that content cannot be recovered - If everything loaded fine, an `ok` message can be used - If the component is using features which are not allowed by policies, `warning` messages can be generated. Log levels are: + - **NORMAL** to be emitted when running the program normally - **SILENT** to be emitted when running the program even in silent mode - **VERBOSE** to be emitted when running the program in verbose mode only - **DEBUG** to be emitted always when running a debug build or in debugging mode. Each messagge must specify their semantic type and log level (normal by default). Usually: + - `panic` messages have a `silent` log level - `ok` and `continue` messages are usually `verbose` - `info`, `warning` and `log` are usually `normal` - -## Logging - -### Debug logging - -**vs** has some features to simplify debugging, mostly to support automatic tests and benchmarks, but they might be useful in other scenarios as well. -`vs::globals::debug` is responsible for that, and it is exposed in several ways: - -- within embedded scripts -- via a special xml `debug` tag -- in the `vs.fltk` C interface as well - While using it you can define a key and value. The current timestamp at nanoseconds resolution is also automatically recorded. - Records are saved to a file with name `VS_DEBUG_FILE` if set, otherwise no output will be emitted. Older content is destroyed. - The file format is just a simple CSV with horizontal tabs as separator of fields and newlines for rows. The order is _key_, _value_ & _timestamp_. - -`vs::globals::debug` should not be confused with the ordinary logging functions which are also exposed in similar ways, but which are generally contextual and they mostly output to `stdout`. - -## Testing