Improving documentation

README.md

@@ -125,6 +125,12 @@ Compared to other approaches, `vs` is extremely opinionated and tries to enforce
 
 You can read more about which features are planned in the [milestones page](./docs/milestones.md).
 
+## Useful documentation
+
+- Instuctions [for developers](./docs/for-developers.md)
+- Instuctions ~~[for users](./docs/for-users.md) of vs~~
+- Complete ~~[specifications](./docs/specs.md)~~.
+
 ## Licences
 
 Currently, most of this project is source available, under the terms of CC BY-ND.  

docs/for-developers.md

@@ -7,18 +7,37 @@ In addition to that, this repo makes use of:
 - [meson](https://mesonbuild.com/) as its main build system. Any recent-ish version will do (unless you need `zig` to simplify cross-compiling; for that >= 1.60 is needed)
 - [bun](https://bun.sh/) as the ts/js runtime to support all the code generation tasks and some of the more complex pipelines.  
    I hate bash, and this is what replaces it.
-- [swiftc](https://www.swift.org/documentation/swift-compiler/) barely used for now, but many of the native components shipped will be written in it (or so I am planning). Swift 6 will be needed, but for now any version will do.
+- [swiftc](https://www.swift.org/documentation/swift-compiler/) barely used for now, but many of the native components shipped within vs will be written in swift (or so I am planning). Swift 6 will be needed, but for now any version will do.
+
+There are also some more or less optional dependencies:
 - **libcurl-dev**, unless you are trying to compile a custom version without network support, which is supported.
+- **sqlite** is needed. If not provided by your system it will be automatically downloaded and distributed alongside `vs`.
+- [flatpak-builder](https://docs.flatpak.org/en/latest/flatpak-builder.html) if you plan on packing and distributing a flatpak of `vs` (usually not needed, read more about it later in this document)
+
+### IDE integrations
+
+There is an ongoing effort to write and release a minimal LSP and vscode extension.  
+Once it is ready enough TODO add link here.
+
+## Supported platforms
 
 At the moment, only Linux is supported or tested, probably on any of the major CPU architectures. Wider support for POSIX systems is also likely.  
 This is just temporary limitation, as all dependencies are portable, but my own code is probably not.
 
-### Optional features
+| **Platform**           | **Building** | **Running** |
+|------------------------|:------------:|:-----------:|
+| debian-trixie amd64    | ✅            | ✅           |
+| freedektop-24.08 amd64 | ✅*           | ✅*          |
+| macos-13 amd64         | ❓            | ❓           |
+| macos-14 arm64         | ❓            | ❓           |
 
-There is an ongoing effort to write and release a minimal LSP and vscode extension. Once it is ready TODO add link here.
 
 ## Building process
 
+This project uses meson and not git submodules for the most part, but there is a specific exception to make `flatpak-builder` usable.  
+If you plan on using it to generate new flatpak images, please ensure submodules are also cloned.
+
+
 Start by installing all the `bun` dependencies needed:
 ```bash
 bun install
@@ -27,11 +46,11 @@ bun install
 Then run the following npm scripts:
 
 ```bash
-bun run codegen             #Initial codegen from schemas
-bun run meson-setup         #Set up the meson builddir
+bun run codegen                     #Initial codegen from schemas
+bun run meson-setup.release         #Set up the meson build directory.
 ```
 
-You might want to use `meson-setup.clang` to use clang-19 if installed in your system, and the default compiler might not support all the modern features needed.  
+You might want to use `meson-setup.clang-release` to use clang-19 if found on your system, and your default compiler or choice might not support some modern functions used in this project.  
 
 
 To perform tests and benchmarks:
@@ -41,7 +60,7 @@ bun run test
 bun run benchmark
 ```
 
-To run the dev demo where features under development are tested:
+To run the dev demo where features under development are usually being tested:
 
 ```bash
 bun run vs.example
@@ -61,16 +80,18 @@ at the end of the library generation. The issue is tracked [here](https://github
 ## Installation
 
 > [!WARNING]  
-> Don't install it via `meson install ...` without a custom `DESTDIR` set, like it is done in the `package.json` script.  
+> Don't install it via `meson install ...` without a custom `DESTDIR` set, as shown by its wrapper in `package.json` script.  
 > Some library names will most surely clash with those already installed on your system, and will be overridden.  
+> Or future system updates might break `vs`.  
 > `vs.fltk` is using very recent versions which have not been rolled out yet in most distribution. Or even worse, custom forks.
 
-`meson-install` is now implemented & tested. By default, it installs everything in `./build/dist`.
+`bun run meson-install` is now implemented & tested. By default, it installs everything in `./build/dist`.
 
 ### Flatpak
 
-Flatpak is not really the ideal approach to deliver `vs` due to the intrinsic cost of having a separate runtime. Also its sandboxing & permission system might raise some issues.  
-Still, it is good to support it at these early stages, since many libraries & build dependencies are bleeding-edge.
+Flatpak is not really the ideal approach to deliver `vs` due to the intrinsic cost of having a separate runtime.  
+Also, its sandboxing & permission system might raise some issues (but also help to mitigate the current lack of safety features).  
+Still, it is good to support it at these early stages, since many libraries & build dependencies are bleeding-edge, and other forms of distribution are not as convenient.
 
 ```sh
 flatpak --user remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo
@@ -86,7 +107,8 @@ bun run flatpak-builder
 ## A word about code generation
 
 A significant portion of code in this repository is generated automatically and does not ship with your `git clone`.  
-Make sure you run `bun run codegen` before you attempt any further step with meson. I will probably integrate it as part of the meson setup step.
+Make sure you run `bun run codegen` before you attempt any further step with meson.  
+I will probably integrate it as part of the meson setup step, but I am still evaluating the potential drawbacks.
 
 The main source for automatic code generation is located in `/schemas` and are JSON files. *Component definitions* are compiled down into C++ classes, c bindings, typescript type definitions, XSD/RND schemas and XML data used in the embedded editor of `vs`.  
 Any component shipped with `vs` (not those externally distributed in `/components`) must have a JSON schema definition, even if their class definition is not automatically generated. In that case the property `use_main_header` is set, but *props* and *computed values* are still defined via JSON schemas.
@@ -110,7 +132,7 @@ In either case, such files are not tracked by git.
 - **docs** this documentation.
 - **bindings** bindings for all languages supported in embedded `script`.
 - **scripts** utility scripts (mostly in TS/JS) for the building process and distribution.
-- **schemas** high level specs, source of information for documentation and automatic code-gen.
+- **schemas** high level specs, souinrce of information for documentation and automatic code-gen.
 - **commons** extra public files (some auto-generated) which are part of every **vs** distribution.
 
 ## Debug logging
@@ -130,10 +152,13 @@ The file format is just a simple CSV with horizontal tabs as separator of fields
 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.
 
-## About exceptions & memory allocations
+## Programming guidelines
+
+### About exceptions
 Exceptions are fully allowed in the CLI at `/src/app`.  
 However, they are strongly discouraged anywhere else in the library code, and it is possible they will be fully disabled via `-fno-exceptions` at some point. The main reason is that the UI should be fault-tolerant and provide as much functionality as possible even if parts of it are broken, like malformed XML files, some scripts failing compilation, missing resources and so on. Exceptions, in this sense, are internally handled and semantically supported by providing subtrees to be rendered in case of failure events.   
 Exceptions should only be used in those cases when the application **must** stop, either because the error is not recoverable or because it would leave the rest of the application in an inconsistent state.  
 
+### Memory allocations
 As for memory allocations, spawning small dynamic objects is also discouraged. If possible, stack allocations are a better alternative. Arrays with variable length on stack are totally fine to be used in place of local objects allocated on heap.  
 `std::string` is also highly discouraged, make sure `std::string_view` is used instead whenever possible.