https://github.com/ardaku/nucleide
A crate to manipulate custom sections of a WebAssembly module to view/edit application metadata.
https://github.com/ardaku/nucleide
metadata-management wasm webassembly
Last synced: 7 months ago
JSON representation
A crate to manipulate custom sections of a WebAssembly module to view/edit application metadata.
- Host: GitHub
- URL: https://github.com/ardaku/nucleide
- Owner: ardaku
- License: apache-2.0
- Created: 2022-04-18T23:40:03.000Z (over 3 years ago)
- Default Branch: stable
- Last Pushed: 2023-09-06T21:57:06.000Z (about 2 years ago)
- Last Synced: 2025-02-28T12:42:43.732Z (8 months ago)
- Topics: metadata-management, wasm, webassembly
- Language: Rust
- Homepage: https://crates.io/crates/nucleide
- Size: 3.71 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE_APACHE_2_0.txt
Awesome Lists containing this project
README
# Nucleide
A crate to manipulate [custom sections] of a WebAssembly module to view/edit
application metadata.
# Specification
Nucleide specifies WASM metadata that is read by the Nucleic Desktop
Environment. It includes the WebAssembly 2.0 and the Daku 1.0.0-beta.0
specifications.
Daku programs are a WebAssembly module that must have the `daku` custom section,
are compressed with ZStd, and should use the `.daku` file extension; thus the
Nucleide specification, as an extension of Daku, shall follow.
App data that can be displayed by a software manager, and where it comes from:
- Non-Localized App Name: `name` section => Module Name Subsection
- Programming Language: `producers` section => Language Field
- Processed With: `producers` section => Processed-By Field
- Generated With: `producers` section => SDK Field
- Required Permissions: `daku` section => Portals Header
- Localized App Names: `daku` section => Translations Subsection
- App Description: `daku` section => Description Translations Subsection
- App Icon Themes: `daku` section => App Icon Themes Subsection
- App Screenshots: `daku` section => Description Assets Subsection
- Searchable Tags: `daku` section => Tags Subsection
- Categories: `daku` section => Categories Subsection
- Organization: `daku` section => Organization Name Subsection
## Types
Nucleide custom sections reuse WebAssembly types:
#### `Byte`
Simply an 8-bit integer.
#### `Integer`
A [Unsigned LEB128] variable-length encoded litte-endian integer, with a maximum
value of 2³²-1 (can be anywhere from 1-5 bytes).
#### `Vector[T]`
A sequence of the following:
- `size: Integer`
- `data: [T; size]`
#### `Name`
Containing valid UTF-8 (no null termination); wrapper around:
- `Vector[Byte]`
#### `NameMap`
A `Vector`, with each element containing a sequence of the following:
- `index: Integer` - Must be sorted in sequence
- `name: Name`
#### `IndirectNameMap`
A `Vector`, with each element containing a sequence of the following:
- `index: Integer` - Must be sorted in sequence
- `name_map: NameMap`
## Custom Sections
### Name (`name`)
From [the wasm spec], debug info. It is expected that apps are built with this
module generated for easier debugging, but stripped away and put into a separate
`.name` file for distribution.
- `subsection: u8`: Each subsection is optional, and must be placed in this
order:
- 0 => Module Name
- 1 => Function Names
- 2 => Local Names
- 3 => Ext: Label Names
- 4 => Ext: Type Names
- 5 => Ext: Table Names
- 6 => Ext: Memory Names
- 7 => Ext: Global Names
- 8 => Ext: Element Names
- 9 => Ext: Data Names
- `size: u32`: Number of bytes
#### 0 => Module Name
- `name: Name`: Name of the app
#### 1 => Function Names
- `name_map: NameMap`: Names of each function
#### 2 => Local Names
- `indirect_name_map: IndirectNameMap`: Names of each variable in each function
#### 3 => Ext: Label Names
- `indirect_name_map: IndirectNameMap`: Names of each label in each function
#### 4 => Ext: Type Names
- `name_map: NameMap`: Names of each type
#### 5 => Ext: Table Names
- `name_map: NameMap`: Names of each table
#### 6 => Ext: Memory Names
- `name_map: NameMap`: Names of each memory
#### 7 => Ext: Global Names
- `name_map: NameMap`: Names of each global
#### 8 => Ext: Element Names
- `name_map: NameMap`: Names of each element
#### 9 => Ext: Data Names
- `name_map: NameMap`: Names of each data
### Producers (`producers`)
From WebAssembly's [tool conventions], information on how the `.daku`
WebAssembly file was generated.
A `Vector`, with each element containing a sequence of the following:
- `name: Name` - One of:
- `"language"`
- `"processed-by"`
- `"sdk"`
- `tool_version_pairs: Vector<(String, String)>`
### Daku (`daku`)
- `portals: Vector`: List of Portal IDs
Following the Daku portals list, is the nucleide extension:
- `subsection: u8`: Each subsection is optional, and must be placed in this
order:
- 0 => Reserved for potential breaking 2.0 version of Daku
- 1 => App Name Translations
- 2 => App Description Translations
- 3 => App Icon Themes
- 4 => App Description Assets
- 5 => Searchable Tags
- 6 => Searchable Categories
- 7 => Organization Name
- `size: u32`: Number of bytes
#### 1 => App Name Translations
- `localized_names: NameMap`
Integer representation of a 4-letter (2-letter lowercase language, 2-letter
uppercase region) locale ASCII description:
- `locale: b"enUS"`
```C
locale[0] | locale[1] << 7 | locale[2] << 14 | locale[3] << 21
```
#### 2 => App Description Translations
- `localized_mdfiles: NameMap`: Markdown file for each description
Integer representation of a 4-letter (2-letter lowercase language, 2-letter
uppercase region) locale ASCII description:
- `locale: b"enUS"`
```C
locale[0] | locale[1] << 7 | locale[2] << 14 | locale[3] << 21
```
#### 3 => App Icon Themes
A `Vector`, with each element containing a sequence of the following:
- `name: Name`: Theme name, `"default"` or `"reduced"`; reduced theme should be
binary (on/off) RGBA. default is full 0-255 range for each.
- `data: Vector`: Concatenated list of [QOI] (future: or [RVG]) files.
Best resolution out of the files will be chosen. None can have the same
resolution.
#### 4 => App Description Assets
A `Vector`, with each element containing a sequence of the following:
- `locale: Integer`: Set to 0 for non-localized assets.
- `path: Name`: Markdown path
- `data: Vector`: [QOI] (future: or [RVG]) file.
#### 5 => Searchable Tags
A `Vector` (limit 8), with each element containing:
- `tag: Name`: Name of the tag (all lowercase ASCII english words separated by
spaces; no `-` or `_`, other punctuation)
#### 6 => Searchable Categories
A `Vector` (limit 2), with each element containing:
- `tag: Byte`: App Category, one of:
- 0 => Media - Applications for playing / recording / editing audio, video,
drawing, photos, fonts, 3D-modeling
- 1 => Office - Applications for viewing / editing / translating documents and
spreadsheets
- 2 => System - Applications for inspecting the operating system, tweaking,
installing, and virtualization
- 3 => Coding - Applications for software development, math, related tools
- 4 => Internet - Applications for browsing the web, peer-to-peer file
sharing, email, social media, etc.
- 5 => Gaming - Applications for playing video games
- 6 => Science - Applications for simulations, electrical/mechanical
engineering, A/I for inspecting data, robots
- 7 => Education - Applications for education, learning
- 8 => Life - Applications to-do lists, calendar, wellbeing, fitness,
directions, mapping, weather, smart home, etc.
- 9 => Finance - Applications for coupons, buying/selling, trading, currency
#### 7 => Organization Name
- `organization: Name`: Name of organization that developed the software
[custom sections]: https://webassembly.github.io/spec/core/binary/modules.html#index-2
[the wasm spec]: https://webassembly.github.io/spec/core/appendix/custom.html#name-section
[QOI]: https://qoiformat.org/qoi-specification.pdf
[RVG]: https://github.com/ardaku/rvg/blob/master/RVG.md
[Unsigned LEB128]: https://en.wikipedia.org/wiki/LEB128#Unsigned_LEB128
[tool conventions]: https://github.com/WebAssembly/tool-conventions/blob/main/ProducersSection.md