From af49133ce8f413b453eb308d71bc78e522457139 Mon Sep 17 00:00:00 2001 From: karurochari Date: Thu, 28 Nov 2024 13:46:16 +0000 Subject: [PATCH] Fix #20. Writing specs --- docs/specs.md | 119 ++++++++++++++++++++++++++++++++++++---- src/pipelines/tcc-c.cpp | 4 +- 2 files changed, 111 insertions(+), 12 deletions(-) diff --git a/docs/specs.md b/docs/specs.md index 35586f02..f8cc3ebe 100644 --- a/docs/specs.md +++ b/docs/specs.md @@ -4,22 +4,106 @@ > Broadly speaking, they target **at least** `v0.5.x` from the [milestone page](./milestones.md) # Quick overview -`vs` is a lightweight runtime to create and run custom user interfaces based on [fltk]. -It aims to be fast, to fit on systems with limited resources, and to run on virtually any platform. -The `vs` runtime is distributed alongside several tools and libraries: -- A workspace/explorer (self-hosted) to quickly access local and remote apps, handle updates and setup safety policies. -- A UI builder/IDE (self-hosted), to visually inspect or write custom components and applications. -- C bindings to write custom native components, while leveraging most features internally offered by `vs`. -- A langugage server & extension to handle `.vs` and `.tvs` files directly in vscode or compatible editors. + +`vs` is a lightweight runtime to design and run custom user interfaces based on [fltk](https://www.fltk.org/). +It aims to be fast, to fit on systems with limited resources available, and to run on virtually any platform. +The `vs` runtime ships with several built-in features, tools and libraries: + +- A self-hosted workspace/explorer to quickly access local and remote apps, to update `vs`, and to visually customize user settings. +- A self-hosted UI builder/IDE to visually inspect, debug or write custom components and applications. +- C bindings to expose most features and allow custom native components from third parties. +- A language server & extension to directly handle `.vs` and `.tvs` files in vscode and compatible editors. + +## Structure of an application + +- An entry-point file referred as **app**, whose root element is `app`. +- **Components**, whose root element is `component`, either used from the entry-point file or other components. +- **Data sources**, usually files with a specific format or endpoints with a well-defined interface. +- **Assets** like images. +- An optional **external application** usually as a dynamic library linked with the **app**, or indirectly used via a Unix socket domain. + +Furthermore, there are additional elements which are not controlled by those writing the app, but on the user side: + +- A storage where secrets and persistent data can be saved. +- A profile with clear permissions and safety policies. An application can provide one as asset suggesting the user to adopt it, but it has no control over what the user decides. + +Both **apps** and **components** can be either specified as final `vs` xml files, or they can be the result of some static data and a template compiled down into "final" xml files. + +# Basic VS elements + +## app + +### attributes + +- `token` +- `link-with` + +## component + +## namespace + +## import + +## use + +## data + +### attributes + +- `src` +- `filter` +- `sort` +- `order` + +## debug + +### attributes + +- `key` +- `value` + +## viewport + +### attributes + +- `src` + +## elements with a frame + +#### attributes + +- `name` +- `mixins` +- `frame.mode` +- `frame.acces` +- `frame.type` + +### script + +#### attributes + +- `lang` +- `src` +- `type` +- `compact` + +### mixins + +#### attributes + +### semantics # Using components + There are two ways to use other components inside others or within your app: + - Via `vs:use`, suggested for cases where it is only needed once. - Adding a `vs:import` directive in the app/component, and using it as an element under the specified name. There is also `vs:viewport` which does something similar, but in this case a new root is rendered within your document, with no event or symbol being passed top/down or bottom/up. ### Examples + ```xml @@ -35,23 +119,29 @@ There is also `vs:viewport` which does something similar, but in this case a new ``` ## Names + Names are unique identifiers within a namespace for components. Adding a name to a component instance also implies that a vs frame is created for it. The converse is also true, and if no explicit name is assigned, one will be automatically generated. Related to names there are two undefined behaviours: + - Giving the same name to two or more elements within the same namespace. - Accessing elements for which the name has not been manually defined. ### Restrictions on names + At this time, no restriction on names has been defined nor implemented. ## Scope of visibility -The scope within names are visible is called *namespace*. A namespace is not strictly speaking equivalent to the UI tree structure, and all elements within a namespace, regardless of their child/parent ordering, are mutually visible. + +The scope within names are visible is called _namespace_. A namespace is not strictly speaking equivalent to the UI tree structure, and all elements within a namespace, regardless of their child/parent ordering, are mutually visible. ### Transparent nodes + Some elements will have their associated frame and name, but their mode is set to `transparent`. In this case any child will be part of the same namespace as their parent, ignoring their tree dependency. ### Limitations on visibility + Elements for which their mode is set to `container` or `slot-container` will prevent name resolution upwards from children. Elements for which their mode is set to `slot` or `slot-container` will prevent name resolution downwards to its children from nodes above it. A node, will always be able to access up and down, regardless of the mode set. Limitations are only for others going through it. @@ -75,7 +165,8 @@ A node, will always be able to access up and down, regardless of the mode set. L ## Event propagation ## Scripts -Embedded scripts are + +Embedded scripts are ### Single user scripts @@ -107,6 +198,7 @@ Embedded scripts are Templating is based on a `vs.templ`, a custom XML preprocessor loosely inspired by [xslt](). Its documentation can be found on its separate repository [here](https://github.com/karurochori/vs-templ). Within the context of `vs.fltk`, using templates involves two files: + - the static dataset which contains any structured needed by the final generation. For vs, its root must be `` and provide a `template` attribute pointing to the actual component template. The suggested extension is `.vs`, the same as normal components. - the template itself, containing a `vs` tree structure and templating commands as well. Its conventional extension is `.tvs`. These files should never be used as components on their own. @@ -115,10 +207,17 @@ When importing or using a component which requires processing, it is compiled an You can find an example for a [dataset](../examples/test-templ.vs) & its associated [template](../examples/test-templ.tvs). # Data + ## General structure + ## Subtypes + ### CSV + ### FS + ### JSON + ### SQLITE -### XML \ No newline at end of file + +### XML diff --git a/src/pipelines/tcc-c.cpp b/src/pipelines/tcc-c.cpp index baaa5014..cd08f42f 100644 --- a/src/pipelines/tcc-c.cpp +++ b/src/pipelines/tcc-c.cpp @@ -50,8 +50,8 @@ std::shared_ptr tcc_c_pipeline(bool is_runtime, vs::ui_base* obj, const cha script->set_out_type(tcc::memory); - script->add_sysinclude_path((globals::path_env.root.location+"./bindings/native/tcc/include").c_str()); - script->add_include_path((globals::path_env.root.location+"./bindings/native/include").c_str()); + script->add_sysinclude_path((globals::path_env.root.location+"bindings/native/tcc/include").c_str()); + script->add_include_path((globals::path_env.root.location+"bindings/native/include").c_str()); //script->add_lib("ld"); //script->add_lib("tcc1");