dymokomi/luce-browser-css
Source of release 0.5.1
0.5.1 / docs / regions / r12c.md
# Region r12c: the generated CSS data (`css_data`) — what other regions need to know
Ladybird generates LibWeb's CSS data at build time: `Build/Libraries/LibWeb/CSS/PropertyID.*`,
`Keyword.*`, `Enums.*`, `Units.*`, `DescriptorID.*`, `EnvironmentVariable.*`, `MathFunctions.*`,
`MediaFeatureID.*`, `PseudoClass.*`, `PseudoElement.*` and `TransformFunctions.*`, about 49,000
lines of C++ written by the Python programs in `Meta/Generators` from the JSON files in
`Libraries/LibWeb/CSS`. Region r12c does not hand-port that C++. It ports the generators:
- **The generator.** `tools/gen_css/` is a Luce program. It reads the JSON inputs, copied into
`data/css` with Ladybird's BSD-2 notice (`data/css/LICENSE`), and writes the `generated_*`
fragments of `css_data`:
| Fragment | Donor files | Ported generator | Input |
| --- | --- | --- | --- |
| `generated_descriptor_id` | `DescriptorID.h/.cpp` | `generate_libweb_css_descriptors.py` | `Descriptors.json` |
| `generated_enums` | `Enums.h/.cpp` | `generate_libweb_css_enums.py` | `Enums.json` |
| `generated_environment_variable` | `EnvironmentVariable.h/.cpp` | `generate_libweb_css_environment_variables.py` | `EnvironmentVariables.json` |
| `generated_keyword` | `Keyword.h/.cpp` | `generate_libweb_css_keyword.py` | `Keywords.json` |
| `generated_math_functions` | `MathFunctions.h/.cpp` | `generate_libweb_css_math_functions.py` | `MathFunctions.json` |
| `generated_media_feature_id` | `MediaFeatureID.h/.cpp` | `generate_libweb_css_media_feature_id.py` | `MediaFeatures.json` |
| `generated_property_id`, `_2`, `_3` | `PropertyID.h/.cpp` | `generate_libweb_css_property_id.py` | `Properties.json`, `Enums.json`, `LogicalPropertyGroups.json` |
| `generated_pseudo_class` | `PseudoClass.h/.cpp` | `generate_libweb_css_pseudo_class.py` | `PseudoClasses.json` |
| `generated_pseudo_element` | `PseudoElement.h/.cpp` | `generate_libweb_css_pseudo_element.py` | `PseudoElements.json` |
| `generated_transform_functions` | `TransformFunctions.h/.cpp` | `generate_libweb_css_transform_functions.py` | `TransformFunctions.json` |
| `generated_units` | `Units.h/.cpp` | `generate_libweb_css_units.py` | `Units.json` |
Each emitter follows its Python generator in order: the same validations, the same iteration
over the JSON in file order, and the same C++ turned into Luce. A `switch` is a `match`. A
`case A: case B: return true;` group becomes one arm per case. `VERIFY_NOT_REACHED()` is
`trap("VERIFY_NOT_REACHED")`.
- **The hand-written fragments:**
- `property_name`: `is_a_custom_property_name_string` and `is_invalid_custom_property_name_string`
(see below);
- `statics`: the slots of the generated function-local statics;
- `types_traits`: the trait bodies.
- **Regenerating.** `test.sh` builds the generator, regenerates into a temporary directory, and
compares with the committed fragments. To change the data, edit `data/css/*.json` and run
`build/gen_css data/css src/css_data`.
The JSON reader is the generator's own (`tools/gen_css/json.lucb`, about 200 lines). It keeps
object members in file order, as Python's `json.load` does, and keeps number text, so that
`Units.json`'s ratios are printed as Python prints them. A reader of our own avoids a dependency of
the package on luce-json that only the tool would use.
## Checked against the donor
- **Locally.** A C++ program is linked with the reference build's objects of the eleven
generated files. It prints what every function answers:
- for every enum value, and every pair the functions take (property × keyword, at-rule ×
descriptor, pseudo-element × property, unit × unit, property × writing mode × direction);
- for 5,797 input strings: every JSON name cased three ways, and strings that are no name.
The same dump from css_data is identical, byte for byte: 15,232 lines, 1.3 MB.
- **In CI.**
- The dump the C++ printed is committed as `tests/data/css_data_dump.txt`, with its inputs in
`tests/data/css_data_inputs.txt`.
- `tests/css_data_dump/` prints css_data's dump, and `test.sh` compares the two. So every
answer of every generated function stays pinned to the donor's generated code.
- `dump_enums.lucb` in that program lists the enums of `Enums.json` and the enum sizes. It was
written out from the JSON at the pin, as the C++ side was.
- **The enums** the generator writes have the same names, types and values as the skeleton's
`types_generated_*`, except the CounterStyleNameKeyword fix below.
- **The 490 stub signatures** are all present with their types. Only parameter names changed:
`arg0` became the C++ definition's name.
## Tests
- Ported: Tests/LibWeb/TestCSSIDSpeed.cpp (`basic`; the benchmark is not ported) and
TestCSSInheritedProperty.cpp.
- `tests_css_data`: focused tests, with values taken from the donor's dump, of:
- keywords, enum conversions and Enums.json aliases;
- property names (FlyStrings made once), camel-case names, custom properties and legacy
aliases;
- flags, quirks, integer and number ranges, keywords and custom-ident blacklists;
- shorthands and longhands, including that a static Vector is made once;
- logical mappings, descriptors, media features, selectors, transform functions, units, and
the enum hash traits.
- The dump comparison above.
## Changes other regions must know
- **The declarations moved.** The enums and structs of these eleven headers now live in the
`generated_*` fragments, written by `tools/gen_css`. The skeleton's `types_generated_*.lucb`
files of `css_data` are deleted. **The skeleton generator must not emit them again**: that
would declare every enum twice. Every name is as the skeleton had it.
- **`is_a_custom_property_name_string` and `is_invalid_custom_property_name_string` moved down.**
They come from `Libraries/LibWeb/CSS/PropertyName.h`, and the generated `property_id_from_string`
and `descriptor_id_from_string` call them. They are now `css_data`'s, a declaration move in the
style of DESIGN.md §4.1.3.
- The engine's stubs `css_is_a_custom_property_name_string` and
`css_is_invalid_custom_property_name_string` should be removed.
- The engine's callers use `css_data.is_a_custom_property_name_string`.
- `is_a_valid_css_property` stays in the engine.
- **Constants.** `first_property_id`, `last_property_id`, `first_inherited_property_id`,
`last_inherited_property_id`, `first_longhand_property_id`, `last_longhand_property_id` and
`number_of_longhand_properties` are `pub let` constants with their values.
- The skeleton had them as zero `pub var`s. Every one of them was `PropertyId.custom` or 0,
which would have been wrong.
- Code that only reads them is unchanged.
- **CounterStyleNameKeyword** is `as u8`, with values 128 and up where the skeleton had wrapped
them to negative `i64` values. The C++ enum is `: u8`, with more than 128 values.
- **Returned Vectors are views of statics.** C++ returns `Vector<PropertyID> const&` from
`longhands_for_shorthand`, `expanded_longhands_for_shorthand`, `shorthands_for_longhand` and
`property_computation_order`.
- The Luce functions return the static Vector by value. It shares the static's buffer.
- Read it; `ak.vector_clone` it before changing it (DESIGN.md §3.3 rule 2).
- `property_custom_ident_blacklist`, `get_descriptor_metadata` and `transform_function_metadata`
return a new Vector per call, as the C++ does.
- **`ak.CaseInsensitiveAsciiStringViewTraits` does not conform to `ak.Traits[StringView]`**, so it
cannot key an `ak.HashMap`. `css_data` has its own conforming struct of that name, which
forwards to ak's two functions. The foundation should make its struct conform (a one-line fix
there). css_data's copy can then go.
- **Not here; the engine's.** These functions of the same generated files build or parse style
values, so they belong to the engine (DESIGN.md §4.1.3). The engine's skeleton stubs them:
- `property_initial_value`, `property_accepts_type` and `property_accepted_ranges_by_value_type`;
- `property_resolves_percentages_relative_to`;
- `property_accepts_{angle,flex,frequency,length,percentage,resolution,time}`;
- `descriptor_initial_value`, `environment_variable_type`, and `Parser::parse_math_function`
with its `parse_rounding_strategy`.
Their generator logic is in the same Python files. It can be added to `tools/gen_css` as a
second output into the engine's `web/generated/` (DESIGN.md §5), by the region that ports them.
## Statics and the collector
The generated C++ keeps function-local statics. `css_data` makes each one a module var with an
initialized flag (DESIGN.md §2.6), filled on first use:
- **The keyword and property tables** (`g_stringview_to_keyword_map`, `properties_table`,
`camel_case_properties_table`) and **the static Vectors** hold only string-literal views and
PropertyIDs. They are built under `with memory.heap`. They live in the C heap for the whole
program, as C++ statics do, whatever allocator is current at the first call, and they need no
root.
- **The static FlyStrings** of `string_from_property_id` and
`camel_case_string_from_property_id` are interned in ak's fly-string table like any FlyString,
with the allocators current at the first call. A module var keeps them.
- When the gc heap is current, their StringData is an atomic blob that only module vars point
to. Module vars are not roots today.
- This is the same open point as ak's own fly-string table: see the foundation's r02 notes,
"GC follow-up". Whatever roots or pins that table (making module data a root range, or
interning fly strings in permanent memory) must cover `css_data`'s
`string_from_property_id_names` and `camel_case_string_from_property_id_names` too.
- Until then, the tests intern under `with memory.heap`.
## Compiler issue
`.donors/luce-browser-tools/compiler-issues/lambda_body_module_type.lucb`: a lambda body did not
see the types its module declares (`(v: u64) => (Color)(u8)v` failed with "unknown type `Color`"),
and a lambda that calls a module function drew a misleading "a lambda captures nothing"
diagnostic. Fixed in Luce 0.8.13; the dump program passes lambdas for the enum conversions.