From e36b4e0ce9940e21f3a4f2c78ddad295fb61ee24 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 18 Jan 2023 19:18:32 -0600 Subject: devel-docs: Organize the table of contents in groups based on interest Part-of: --- devel-docs/index.rst | 30 ++++++++++++++++++++++++++---- 1 file changed, 26 insertions(+), 4 deletions(-) diff --git a/devel-docs/index.rst b/devel-docs/index.rst index 34625c15..9d9ea374 100644 --- a/devel-docs/index.rst +++ b/devel-docs/index.rst @@ -2,21 +2,42 @@ Development guide for librsvg ============================= .. toctree:: + :caption: For Distributors and end users + :maxdepth: 1 + product roadmap + +.. toctree:: + :caption: Getting started as a Contributor + :maxdepth: 1 + devel_environment + contributing + +.. toctree:: + :caption: Understand the code + :maxdepth: 1 + architecture adding_a_property memory_leaks - contributing - ci + +.. toctree:: + :caption: Design documents + :maxdepth: 1 + text_layout render_tree api_observability performance_tracking - releasing + +.. toctree:: + :caption: Info for Maintainers :maxdepth: 1 - :caption: Contents: + + releasing + Continuous Integration Welcome to the developer's guide for librsvg. This is for people who want to work on the development of librsvg itself, not for users of @@ -80,6 +101,7 @@ Information for maintainers --------------------------- - :doc:`releasing` +- :doc:`ci` Overview of the maintainer's workflow. -- cgit v1.2.1 From 93958d6d442723a114c952f44e17a98baa58b215 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 18 Jan 2023 19:34:59 -0600 Subject: devel-docs: Move the list of FEATURES.md to the development guide Part-of: --- FEATURES.md | 449 --------------------------- devel-docs/features.rst | 801 ++++++++++++++++++++++++++++++++++++++++++++++++ devel-docs/index.rst | 2 + 3 files changed, 803 insertions(+), 449 deletions(-) delete mode 100644 FEATURES.md create mode 100644 devel-docs/features.rst diff --git a/FEATURES.md b/FEATURES.md deleted file mode 100644 index 9e9570ea..00000000 --- a/FEATURES.md +++ /dev/null @@ -1,449 +0,0 @@ -# SVG and CSS features that librsvg supports - -Table of contents: - -[[_TOC_]] - -Librsvg tries to be a mostly complete renderer for SVG1.1 and SVG2. - -In terms of processing external references, librsvg is a bit more -strict than SVG's "static mode" and a bit more lenient than "secure -static mode". See "Security and locations of referenced files" in the -reference documentation for details. - -Animation, interactivity, and scripting are not supported. - -The SVG1.2 specification never made it past draft status in the W3C's -process, and librsvg does not support it. Note that SVG2 removed some -of the features proposed for SVG1.2. - -Generally, librsvg tries to keep up with features in the SVG2 -Candidate Recommendation spec. It ignores features in the SVG2 -drafts that are not finalized yet. - -Alternative versions of SVG (SVG Tiny, SVG Basic, [SVG -Native](https://gitlab.gnome.org/GNOME/librsvg/-/issues/689)) are not -explicitly supported. Their features which are a subset of SVG1.1 or -SVG2 are supported if they are equivalent to the ones listed below. - -SVG2 offloads many of its features to the family of CSS3 -specifications. Librsvg does not try to support them exhaustively -(there are too many features in CSS!). Instead, we try to prioritize -new features based on the needs which people express in librsvg's bug -tracker. Do you want a feature? [File an -issue](https://gitlab.gnome.org/GNOME/librsvg/issues)! - -# Attributes supported by all elements - -| Attribute | Notes | -| --- | --- | -| class | | -| id | | -| requiredExtensions | Used in children of the `switch` element. | -| requiredFeatures | Used in children of the `switch` element. | -| systemLanguage | Used in children of the `switch` element. | -| style | | -| transform | The `transform` attribute has a different syntax than the CSS `transform` property. | -| xml:lang | | -| xml:space | | - -# Elements and their specific attributes - -| Element | Attributes | Notes | -| --- | --- | --- | -| a | | | -| | xlink:href | Needs xlink namespace | -| | href | SVG2 | -| circle | | | -| | cx | | -| | cy | | -| | r | | -| clipPath | | | -| | clipPathUnits | | -| defs | | | -| ellipse | | | -| | cx | | -| | cy | | -| | rx | | -| | ry | | -| feBlend | | See "Filter effects" | -| | in | | -| | in2 | | -| | mode | | -| feColorMatrix | | See "Filter effects" | -| | in | | -| | type | | -| | values | | -| feComponentTransfer | | See "Filter effects" | -| | in | | -| feComposite | | See "Filter effects" | -| | in | | -| | in2 | | -| | operator | | -| | k1 | | -| | k2 | | -| | k3 | | -| | k4 | | -| feConvolveMatrix | | See "Filter effects" | -| | in | | -| | order | | -| | divisor | | -| | bias | | -| | targetX | | -| | targetY | | -| | edgeMode | | -| | kernelMatrix | | -| | kernelUnitLength | | -| | preserveAlpha | | -| feDiffuseLighting | | See "Filter effects" | -| | in | | -| | surfaceScale | | -| | kernelUnitLength | | -| | diffuseConstant | | -| feDisplacementMap | | See "Filter effects" | -| | in | | -| | in2 | | -| | scale | | -| | xChannelSelector | | -| | yChannelSelector | | -| feDistantLight | | | -| | azimuth | | -| | elevation | | -| feFuncA | | See "Filter effect feComponentTransfer" | -| feFuncB | | See "Filter effect feComponentTransfer" | -| feFuncG | | See "Filter effect feComponentTransfer" | -| feFuncR | | See "Filter effect feComponentTransfer" | -| feFlood | | See "Filter effects" | -| | | Parameters come from the flood-color and flood-opacity properties. | -| feGaussianBlur | | See "Filter effects" | -| | in | | -| | stdDeviation | | -| feImage | | See "Filter effects" | -| | xlink:href | Needs xlink namespace | -| | href | SVG2 | -| | path | Non-standard; used by old Adobe Illustrator versions. | -| | preserveAspectRatio | | -| feMerge | | See "Filter effects" | -| feMergeNode | | | -| | in | | -| feMorphology | | See "Filter effects" | -| | in | | -| | operator | | -| | radius | | -| feOffset | | See "Filter effects" | -| | in | | -| | dx | | -| | dy | | -| fePointLight | | | -| | x | | -| | y | | -| | z | | -| feSpecularLighting | | See "Filter effects" | -| | in | | -| | surfaceScale | | -| | kernelUnitLength | | -| | specularConstant | | -| | specularExponent | | -| feSpotLight | | | -| | x | | -| | y | | -| | z | | -| | pointsAtX | | -| | pointsAtY | | -| | pointsAtZ | | -| | specularExponent | | -| | limitingConeAngle | | -| feTile | | See "Filter effects" | -| | in | | -| feTurbulence | | See "Filter effects" | -| | baseFrequency | | -| | numOctaves | | -| | seed | | -| | stitchTiles | | -| | type | | -| filter | | | -| | filterUnits | | -| | primitiveUnits | | -| | x | | -| | y | | -| | width | | -| | height | | -| g | | | -| image | | | -| | xlink:href | Needs xlink namespace | -| | href | SVG2 | -| | path | Non-standard; used by old Adobe Illustrator versions. | -| | x | | -| | y | | -| | width | | -| | height | | -| | preserveAspectRatio | | -| line | | | -| | x1 | | -| | y1 | | -| | x2 | | -| | y2 | | -| linearGradient | | | -| | gradientUnits | | -| | gradientTransform | | -| | spreadMethod | | -| | x1 | | -| | y1 | | -| | x2 | | -| | y2 | | -| marker | | | -| | markerUnits | | -| | refX | | -| | refY | | -| | markerWidth | | -| | markerHeight | | -| | orient | | -| | preserveAspectRatio | | -| | viewBox | | -| mask | | | -| | x | | -| | y | | -| | width | | -| | height | | -| | maskUnits | | -| | maskContentUnits | | -| path | | | -| | d | | -| pattern | | | -| | xlink:href | Needs xlink namespace | -| | href | SVG2 | -| | patternUnits | | -| | patternContentUnits | | -| | patternTransform | | -| | preserveAspectRatio | | -| | viewBox | | -| | x | | -| | y | | -| | width | | -| | height | | -| polygon | | | -| | points | | -| polyline | | | -| | points | | -| radialGradient | | | -| | gradientUnits | | -| | gradientTransform | | -| | spreadMethod | | -| | cx | | -| | cy | | -| | r | | -| | fx | | -| | fx | | -| | fr | | -| rect | | | -| | x | | -| | y | | -| | width | | -| | height | | -| | rx | | -| | ry | | -| stop | | | -| | offset | | -| style | | | -| | type | | -| svg | | | -| | x | | -| | y | | -| | width | | -| | height | | -| | viewBox | | -| | preserveAspectRatio | | -| switch | | | -| symbol | | | -| | preserveAspectRatio | | -| | viewBox | | -| text | | | -| | x | | -| | y | | -| | dx | | -| | dy | | -| tref | | | -| | xlink:href | Needs xlink namespace | -| tspan | | | -| | x | | -| | y | | -| | dx | | -| | dy | | -| use | | | -| | xlink:href | Needs xlink namespace | -| | href | SVG2 | -| | x | | -| | y | | -| | width | | -| | height | | - -# CSS properties - -The following are shorthand properties. They are not available as -presentation attributes, only as style properties, so for example you have to use -``, since there is no `marker` attribute. - -| Property | Notes | -|----------------------------|--------------------------------------------------------------------| -| font | | -| glyph-orientation-vertical | Supports only CSS Writing Modes 3 values: auto, 0, 90, 0deg, 90deg | -| marker | | - -The following are longhand properties. Most of them are available as -presentation attributes, e.g. you can use `` as -well as ``. The Notes column indicates -which properties are not available as presentation attributes. - -| Property | Notes | -|-----------------------------|--------------------------------------------------------| -| baseline-shift | | -| clip-path | | -| clip-rule | | -| color | | -| color-interpolation-filters | | -| direction | | -| display | | -| enable-background | | -| fill | | -| fill-opacity | | -| fill-rule | | -| filter | | -| flood-color | | -| flood-opacity | | -| font-family | | -| font-size | | -| font-stretch | | -| font-style | | -| font-variant | | -| font-weight | | -| isolation | Not available as a presentation attribute. | -| letter-spacing | | -| lighting-color | | -| line-height | Not available as a presentation attribute. | -| marker-end | | -| marker-mid | | -| marker-start | | -| mask | | -| mask-type | | -| mix-blend-mode | Not available as a presentation attribute. | -| opacity | | -| overflow | | -| paint-order | | -| shape-rendering | | -| stop-color | | -| stop-opacity | | -| stroke | | -| stroke-dasharray | | -| stroke-dashoffset | | -| stroke-linecap | | -| stroke-linejoin | | -| stroke-miterlimit | | -| stroke-opacity | | -| stroke-width | | -| text-anchor | | -| text-decoration | | -| text-orientation | Not available as a presentation attribute. | -| text-rendering | | -| transform | SVG2; different syntax from the `transform` attribute. | -| unicode-bidi | | -| vector-effect | Only `non-scaling-stroke` is supported for paths. | -| visibility | | -| writing-mode | | - -## Filter effects - -The following elements are filter effects: - -* feBlend -* feColorMatrix -* feComponentTransfer -* feComposite -* feConvolveMatrix -* feDiffuseLighting -* feDisplacementMap -* feFlood -* feGaussianBlur -* feImage -* feMerge -* feMorphology -* feOffset -* feSpecularLighting -* feTile -* feTurbulence - -All of those elements for filter effects support these attributes: - -| Attribute | Notes | -| --- | --- | -| x | | -| y | | -| width | | -| height | | -| result | | - -Some filter effect elements take one input in the `in` attribute, and -some others take two inputs in the `in`, `in2` attributes. See the -table of elements above for details. - -## Filter effect feComponentTransfer - -The `feComponentTransfer` element can contain children `feFuncA`, -`feFuncR`, `feFuncG`, `feFuncB`, and those all support these -attributes: - -| Attribute | Notes | -| --- | --- | -| type | | -| tableValues | | -| slope | | -| intercept | | -| amplitude | | -| exponent | | -| offset | | - -# CSS features - -## Pseudo-classes - -| Pseudo-class | Notes | -| --- | --- | -| :link | | -| :visited | Because librsvg does not maintain browser history, this is parsed, but never matches | -| :lang() | | -| :not() | [^1] | -| :first-child | [^1] | -| :last-child | [^1] | -| :only-child | [^1] | -| :root | [^1] | -| :empty | [^1] | -| :nth-child() | [^1] | -| :nth-last-child() | [^1] | -| :nth-of-type() | [^1] | -| :nth-last-of-type() | [^1] | -| :first-of-type | [^1] | -| :last-of-type | [^1] | -| :only-of-type | [^1] | - -[^1]: These structural pseudo-classes are implemented in rust-selectors, which librsvg uses. - -FIXME: which selectors, combinators, at-rules. - -# XML features - -FIXME: `` - -FIXME: `` - -FIXME: `xml:lang` attribute - -FIXME: `xml:space` attribute - -# Explicitly Unsupported features - -* `flowRoot` element and its children - Inkscape, SVG 1.2 only., #13 - -* `glyph-orientation-horizontal` property - SVG1.1 only, removed in SVG2 - -* The pseudo-classes `:is()` and `:where()` are part of Selectors Level 4, which is still a working draft. - -# Footnotes diff --git a/devel-docs/features.rst b/devel-docs/features.rst new file mode 100644 index 00000000..5e5b7df7 --- /dev/null +++ b/devel-docs/features.rst @@ -0,0 +1,801 @@ +SVG and CSS features that librsvg supports +========================================== + +Librsvg tries to be a mostly complete renderer for SVG1.1 and SVG2. + +In terms of processing external references, librsvg is a bit more strict +than SVG’s “static mode” and a bit more lenient than “secure static +mode”. See “Security and locations of referenced files” in the reference +documentation for details. + +Animation, interactivity, and scripting are not supported. + +The SVG1.2 specification never made it past draft status in the W3C’s +process, and librsvg does not support it. Note that SVG2 removed some of +the features proposed for SVG1.2. + +Generally, librsvg tries to keep up with features in the SVG2 Candidate +Recommendation spec. It ignores features in the SVG2 drafts that are not +finalized yet. + +Alternative versions of SVG (SVG Tiny, SVG Basic, `SVG +Native `__) are not +explicitly supported. Their features which are a subset of SVG1.1 or +SVG2 are supported if they are equivalent to the ones listed below. + +SVG2 offloads many of its features to the family of CSS3 specifications. +Librsvg does not try to support them exhaustively (there are too many +features in CSS!). Instead, we try to prioritize new features based on +the needs which people express in librsvg’s bug tracker. Do you want a +feature? `File an +issue `__! + +Attributes supported by all elements +------------------------------------ + ++-----------------------------------+-----------------------------------+ +| Attribute | Notes | ++===================================+===================================+ +| class | | ++-----------------------------------+-----------------------------------+ +| id | | ++-----------------------------------+-----------------------------------+ +| requiredExtensions | Used in children of the | +| | ``switch`` element. | ++-----------------------------------+-----------------------------------+ +| requiredFeatures | Used in children of the | +| | ``switch`` element. | ++-----------------------------------+-----------------------------------+ +| systemLanguage | Used in children of the | +| | ``switch`` element. | ++-----------------------------------+-----------------------------------+ +| style | | ++-----------------------------------+-----------------------------------+ +| transform | The ``transform`` attribute has a | +| | different syntax than the CSS | +| | ``transform`` property. | ++-----------------------------------+-----------------------------------+ +| xml:lang | | ++-----------------------------------+-----------------------------------+ +| xml:space | | ++-----------------------------------+-----------------------------------+ + +Elements and their specific attributes +-------------------------------------- + ++-----------------------+-----------------------+-----------------------+ +| Element | Attributes | Notes | ++=======================+=======================+=======================+ +| a | | | ++-----------------------+-----------------------+-----------------------+ +| | xlink:href | Needs xlink namespace | ++-----------------------+-----------------------+-----------------------+ +| | href | SVG2 | ++-----------------------+-----------------------+-----------------------+ +| circle | | | ++-----------------------+-----------------------+-----------------------+ +| | cx | | ++-----------------------+-----------------------+-----------------------+ +| | cy | | ++-----------------------+-----------------------+-----------------------+ +| | r | | ++-----------------------+-----------------------+-----------------------+ +| clipPath | | | ++-----------------------+-----------------------+-----------------------+ +| | clipPathUnits | | ++-----------------------+-----------------------+-----------------------+ +| defs | | | ++-----------------------+-----------------------+-----------------------+ +| ellipse | | | ++-----------------------+-----------------------+-----------------------+ +| | cx | | ++-----------------------+-----------------------+-----------------------+ +| | cy | | ++-----------------------+-----------------------+-----------------------+ +| | rx | | ++-----------------------+-----------------------+-----------------------+ +| | ry | | ++-----------------------+-----------------------+-----------------------+ +| feBlend | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | in2 | | ++-----------------------+-----------------------+-----------------------+ +| | mode | | ++-----------------------+-----------------------+-----------------------+ +| feColorMatrix | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | type | | ++-----------------------+-----------------------+-----------------------+ +| | values | | ++-----------------------+-----------------------+-----------------------+ +| feComponentTransfer | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| feComposite | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | in2 | | ++-----------------------+-----------------------+-----------------------+ +| | operator | | ++-----------------------+-----------------------+-----------------------+ +| | k1 | | ++-----------------------+-----------------------+-----------------------+ +| | k2 | | ++-----------------------+-----------------------+-----------------------+ +| | k3 | | ++-----------------------+-----------------------+-----------------------+ +| | k4 | | ++-----------------------+-----------------------+-----------------------+ +| feConvolveMatrix | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | order | | ++-----------------------+-----------------------+-----------------------+ +| | divisor | | ++-----------------------+-----------------------+-----------------------+ +| | bias | | ++-----------------------+-----------------------+-----------------------+ +| | targetX | | ++-----------------------+-----------------------+-----------------------+ +| | targetY | | ++-----------------------+-----------------------+-----------------------+ +| | edgeMode | | ++-----------------------+-----------------------+-----------------------+ +| | kernelMatrix | | ++-----------------------+-----------------------+-----------------------+ +| | kernelUnitLength | | ++-----------------------+-----------------------+-----------------------+ +| | preserveAlpha | | ++-----------------------+-----------------------+-----------------------+ +| feDiffuseLighting | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | surfaceScale | | ++-----------------------+-----------------------+-----------------------+ +| | kernelUnitLength | | ++-----------------------+-----------------------+-----------------------+ +| | diffuseConstant | | ++-----------------------+-----------------------+-----------------------+ +| feDisplacementMap | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | in2 | | ++-----------------------+-----------------------+-----------------------+ +| | scale | | ++-----------------------+-----------------------+-----------------------+ +| | xChannelSelector | | ++-----------------------+-----------------------+-----------------------+ +| | yChannelSelector | | ++-----------------------+-----------------------+-----------------------+ +| feDistantLight | | | ++-----------------------+-----------------------+-----------------------+ +| | azimuth | | ++-----------------------+-----------------------+-----------------------+ +| | elevation | | ++-----------------------+-----------------------+-----------------------+ +| feFuncA | | See “Filter effect | +| | | feComponentTransfer” | ++-----------------------+-----------------------+-----------------------+ +| feFuncB | | See “Filter effect | +| | | feComponentTransfer” | ++-----------------------+-----------------------+-----------------------+ +| feFuncG | | See “Filter effect | +| | | feComponentTransfer” | ++-----------------------+-----------------------+-----------------------+ +| feFuncR | | See “Filter effect | +| | | feComponentTransfer” | ++-----------------------+-----------------------+-----------------------+ +| feFlood | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | | Parameters come from | +| | | the flood-color and | +| | | flood-opacity | +| | | properties. | ++-----------------------+-----------------------+-----------------------+ +| feGaussianBlur | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | stdDeviation | | ++-----------------------+-----------------------+-----------------------+ +| feImage | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | xlink:href | Needs xlink namespace | ++-----------------------+-----------------------+-----------------------+ +| | href | SVG2 | ++-----------------------+-----------------------+-----------------------+ +| | path | Non-standard; used by | +| | | old Adobe Illustrator | +| | | versions. | ++-----------------------+-----------------------+-----------------------+ +| | preserveAspectRatio | | ++-----------------------+-----------------------+-----------------------+ +| feMerge | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| feMergeNode | | | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| feMorphology | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | operator | | ++-----------------------+-----------------------+-----------------------+ +| | radius | | ++-----------------------+-----------------------+-----------------------+ +| feOffset | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | dx | | ++-----------------------+-----------------------+-----------------------+ +| | dy | | ++-----------------------+-----------------------+-----------------------+ +| fePointLight | | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | z | | ++-----------------------+-----------------------+-----------------------+ +| feSpecularLighting | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| | surfaceScale | | ++-----------------------+-----------------------+-----------------------+ +| | kernelUnitLength | | ++-----------------------+-----------------------+-----------------------+ +| | specularConstant | | ++-----------------------+-----------------------+-----------------------+ +| | specularExponent | | ++-----------------------+-----------------------+-----------------------+ +| feSpotLight | | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | z | | ++-----------------------+-----------------------+-----------------------+ +| | pointsAtX | | ++-----------------------+-----------------------+-----------------------+ +| | pointsAtY | | ++-----------------------+-----------------------+-----------------------+ +| | pointsAtZ | | ++-----------------------+-----------------------+-----------------------+ +| | specularExponent | | ++-----------------------+-----------------------+-----------------------+ +| | limitingConeAngle | | ++-----------------------+-----------------------+-----------------------+ +| feTile | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | in | | ++-----------------------+-----------------------+-----------------------+ +| feTurbulence | | See “Filter effects” | ++-----------------------+-----------------------+-----------------------+ +| | baseFrequency | | ++-----------------------+-----------------------+-----------------------+ +| | numOctaves | | ++-----------------------+-----------------------+-----------------------+ +| | seed | | ++-----------------------+-----------------------+-----------------------+ +| | stitchTiles | | ++-----------------------+-----------------------+-----------------------+ +| | type | | ++-----------------------+-----------------------+-----------------------+ +| filter | | | ++-----------------------+-----------------------+-----------------------+ +| | filterUnits | | ++-----------------------+-----------------------+-----------------------+ +| | primitiveUnits | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | width | | ++-----------------------+-----------------------+-----------------------+ +| | height | | ++-----------------------+-----------------------+-----------------------+ +| g | | | ++-----------------------+-----------------------+-----------------------+ +| image | | | ++-----------------------+-----------------------+-----------------------+ +| | xlink:href | Needs xlink namespace | ++-----------------------+-----------------------+-----------------------+ +| | href | SVG2 | ++-----------------------+-----------------------+-----------------------+ +| | path | Non-standard; used by | +| | | old Adobe Illustrator | +| | | versions. | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | width | | ++-----------------------+-----------------------+-----------------------+ +| | height | | ++-----------------------+-----------------------+-----------------------+ +| | preserveAspectRatio | | ++-----------------------+-----------------------+-----------------------+ +| line | | | ++-----------------------+-----------------------+-----------------------+ +| | x1 | | ++-----------------------+-----------------------+-----------------------+ +| | y1 | | ++-----------------------+-----------------------+-----------------------+ +| | x2 | | ++-----------------------+-----------------------+-----------------------+ +| | y2 | | ++-----------------------+-----------------------+-----------------------+ +| linearGradient | | | ++-----------------------+-----------------------+-----------------------+ +| | gradientUnits | | ++-----------------------+-----------------------+-----------------------+ +| | gradientTransform | | ++-----------------------+-----------------------+-----------------------+ +| | spreadMethod | | ++-----------------------+-----------------------+-----------------------+ +| | x1 | | ++-----------------------+-----------------------+-----------------------+ +| | y1 | | ++-----------------------+-----------------------+-----------------------+ +| | x2 | | ++-----------------------+-----------------------+-----------------------+ +| | y2 | | ++-----------------------+-----------------------+-----------------------+ +| marker | | | ++-----------------------+-----------------------+-----------------------+ +| | markerUnits | | ++-----------------------+-----------------------+-----------------------+ +| | refX | | ++-----------------------+-----------------------+-----------------------+ +| | refY | | ++-----------------------+-----------------------+-----------------------+ +| | markerWidth | | ++-----------------------+-----------------------+-----------------------+ +| | markerHeight | | ++-----------------------+-----------------------+-----------------------+ +| | orient | | ++-----------------------+-----------------------+-----------------------+ +| | preserveAspectRatio | | ++-----------------------+-----------------------+-----------------------+ +| | viewBox | | ++-----------------------+-----------------------+-----------------------+ +| mask | | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | width | | ++-----------------------+-----------------------+-----------------------+ +| | height | | ++-----------------------+-----------------------+-----------------------+ +| | maskUnits | | ++-----------------------+-----------------------+-----------------------+ +| | maskContentUnits | | ++-----------------------+-----------------------+-----------------------+ +| path | | | ++-----------------------+-----------------------+-----------------------+ +| | d | | ++-----------------------+-----------------------+-----------------------+ +| pattern | | | ++-----------------------+-----------------------+-----------------------+ +| | xlink:href | Needs xlink namespace | ++-----------------------+-----------------------+-----------------------+ +| | href | SVG2 | ++-----------------------+-----------------------+-----------------------+ +| | patternUnits | | ++-----------------------+-----------------------+-----------------------+ +| | patternContentUnits | | ++-----------------------+-----------------------+-----------------------+ +| | patternTransform | | ++-----------------------+-----------------------+-----------------------+ +| | preserveAspectRatio | | ++-----------------------+-----------------------+-----------------------+ +| | viewBox | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | width | | ++-----------------------+-----------------------+-----------------------+ +| | height | | ++-----------------------+-----------------------+-----------------------+ +| polygon | | | ++-----------------------+-----------------------+-----------------------+ +| | points | | ++-----------------------+-----------------------+-----------------------+ +| polyline | | | ++-----------------------+-----------------------+-----------------------+ +| | points | | ++-----------------------+-----------------------+-----------------------+ +| radialGradient | | | ++-----------------------+-----------------------+-----------------------+ +| | gradientUnits | | ++-----------------------+-----------------------+-----------------------+ +| | gradientTransform | | ++-----------------------+-----------------------+-----------------------+ +| | spreadMethod | | ++-----------------------+-----------------------+-----------------------+ +| | cx | | ++-----------------------+-----------------------+-----------------------+ +| | cy | | ++-----------------------+-----------------------+-----------------------+ +| | r | | ++-----------------------+-----------------------+-----------------------+ +| | fx | | ++-----------------------+-----------------------+-----------------------+ +| | fx | | ++-----------------------+-----------------------+-----------------------+ +| | fr | | ++-----------------------+-----------------------+-----------------------+ +| rect | | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | width | | ++-----------------------+-----------------------+-----------------------+ +| | height | | ++-----------------------+-----------------------+-----------------------+ +| | rx | | ++-----------------------+-----------------------+-----------------------+ +| | ry | | ++-----------------------+-----------------------+-----------------------+ +| stop | | | ++-----------------------+-----------------------+-----------------------+ +| | offset | | ++-----------------------+-----------------------+-----------------------+ +| style | | | ++-----------------------+-----------------------+-----------------------+ +| | type | | ++-----------------------+-----------------------+-----------------------+ +| svg | | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | width | | ++-----------------------+-----------------------+-----------------------+ +| | height | | ++-----------------------+-----------------------+-----------------------+ +| | viewBox | | ++-----------------------+-----------------------+-----------------------+ +| | preserveAspectRatio | | ++-----------------------+-----------------------+-----------------------+ +| switch | | | ++-----------------------+-----------------------+-----------------------+ +| symbol | | | ++-----------------------+-----------------------+-----------------------+ +| | preserveAspectRatio | | ++-----------------------+-----------------------+-----------------------+ +| | viewBox | | ++-----------------------+-----------------------+-----------------------+ +| text | | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | dx | | ++-----------------------+-----------------------+-----------------------+ +| | dy | | ++-----------------------+-----------------------+-----------------------+ +| tref | | | ++-----------------------+-----------------------+-----------------------+ +| | xlink:href | Needs xlink namespace | ++-----------------------+-----------------------+-----------------------+ +| tspan | | | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | dx | | ++-----------------------+-----------------------+-----------------------+ +| | dy | | ++-----------------------+-----------------------+-----------------------+ +| use | | | ++-----------------------+-----------------------+-----------------------+ +| | xlink:href | Needs xlink namespace | ++-----------------------+-----------------------+-----------------------+ +| | href | SVG2 | ++-----------------------+-----------------------+-----------------------+ +| | x | | ++-----------------------+-----------------------+-----------------------+ +| | y | | ++-----------------------+-----------------------+-----------------------+ +| | width | | ++-----------------------+-----------------------+-----------------------+ +| | height | | ++-----------------------+-----------------------+-----------------------+ + +CSS properties +-------------- + +The following are shorthand properties. They are not available as +presentation attributes, only as style properties, so for example you +have to use ````, since there is no +``marker`` attribute. + ++----------------------------+--------------------------------------------------------------------+ +| Property | Notes | ++============================+====================================================================+ +| font | | ++----------------------------+--------------------------------------------------------------------+ +| glyph-orientation-vertical | Supports only CSS Writing Modes 3 values: auto, 0, 90, 0deg, 90deg | ++----------------------------+--------------------------------------------------------------------+ +| marker | | ++----------------------------+--------------------------------------------------------------------+ + +The following are longhand properties. Most of them are available as +presentation attributes, e.g. you can use ```` as +well as ````. The Notes column indicates +which properties are not available as presentation attributes. + ++-----------------------+----------------------------------------------+ +| Property | Notes | ++=======================+==============================================+ +| baseline-shift | | ++-----------------------+----------------------------------------------+ +| clip-path | | ++-----------------------+----------------------------------------------+ +| clip-rule | | ++-----------------------+----------------------------------------------+ +| color | | ++-----------------------+----------------------------------------------+ +| color- | | +| interpolation-filters | | ++-----------------------+----------------------------------------------+ +| direction | | ++-----------------------+----------------------------------------------+ +| display | | ++-----------------------+----------------------------------------------+ +| enable-background | | ++-----------------------+----------------------------------------------+ +| fill | | ++-----------------------+----------------------------------------------+ +| fill-opacity | | ++-----------------------+----------------------------------------------+ +| fill-rule | | ++-----------------------+----------------------------------------------+ +| filter | | ++-----------------------+----------------------------------------------+ +| flood-color | | ++-----------------------+----------------------------------------------+ +| flood-opacity | | ++-----------------------+----------------------------------------------+ +| font-family | | ++-----------------------+----------------------------------------------+ +| font-size | | ++-----------------------+----------------------------------------------+ +| font-stretch | | ++-----------------------+----------------------------------------------+ +| font-style | | ++-----------------------+----------------------------------------------+ +| font-variant | | ++-----------------------+----------------------------------------------+ +| font-weight | | ++-----------------------+----------------------------------------------+ +| isolation | Not available as a presentation attribute. | ++-----------------------+----------------------------------------------+ +| letter-spacing | | ++-----------------------+----------------------------------------------+ +| lighting-color | | ++-----------------------+----------------------------------------------+ +| line-height | Not available as a presentation attribute. | ++-----------------------+----------------------------------------------+ +| marker-end | | ++-----------------------+----------------------------------------------+ +| marker-mid | | ++-----------------------+----------------------------------------------+ +| marker-start | | ++-----------------------+----------------------------------------------+ +| mask | | ++-----------------------+----------------------------------------------+ +| mask-type | | ++-----------------------+----------------------------------------------+ +| mix-blend-mode | Not available as a presentation attribute. | ++-----------------------+----------------------------------------------+ +| opacity | | ++-----------------------+----------------------------------------------+ +| overflow | | ++-----------------------+----------------------------------------------+ +| paint-order | | ++-----------------------+----------------------------------------------+ +| shape-rendering | | ++-----------------------+----------------------------------------------+ +| stop-color | | ++-----------------------+----------------------------------------------+ +| stop-opacity | | ++-----------------------+----------------------------------------------+ +| stroke | | ++-----------------------+----------------------------------------------+ +| stroke-dasharray | | ++-----------------------+----------------------------------------------+ +| stroke-dashoffset | | ++-----------------------+----------------------------------------------+ +| stroke-linecap | | ++-----------------------+----------------------------------------------+ +| stroke-linejoin | | ++-----------------------+----------------------------------------------+ +| stroke-miterlimit | | ++-----------------------+----------------------------------------------+ +| stroke-opacity | | ++-----------------------+----------------------------------------------+ +| stroke-width | | ++-----------------------+----------------------------------------------+ +| text-anchor | | ++-----------------------+----------------------------------------------+ +| text-decoration | | ++-----------------------+----------------------------------------------+ +| text-orientation | Not available as a presentation attribute. | ++-----------------------+----------------------------------------------+ +| text-rendering | | ++-----------------------+----------------------------------------------+ +| transform | SVG2; different syntax from the | +| | ``transform`` attribute. | ++-----------------------+----------------------------------------------+ +| unicode-bidi | | ++-----------------------+----------------------------------------------+ +| vector-effect | Only ``non-scaling-stroke`` is supported for | +| | paths. | ++-----------------------+----------------------------------------------+ +| visibility | | ++-----------------------+----------------------------------------------+ +| writing-mode | | ++-----------------------+----------------------------------------------+ + +Filter effects +-------------- + +The following elements are filter effects: + +- feBlend +- feColorMatrix +- feComponentTransfer +- feComposite +- feConvolveMatrix +- feDiffuseLighting +- feDisplacementMap +- feFlood +- feGaussianBlur +- feImage +- feMerge +- feMorphology +- feOffset +- feSpecularLighting +- feTile +- feTurbulence + +All of those elements for filter effects support these attributes: + ++-----------------------------------+-----------------------------------+ +| Attribute | Notes | ++===================================+===================================+ +| x | | ++-----------------------------------+-----------------------------------+ +| y | | ++-----------------------------------+-----------------------------------+ +| width | | ++-----------------------------------+-----------------------------------+ +| height | | ++-----------------------------------+-----------------------------------+ +| result | | ++-----------------------------------+-----------------------------------+ + +Some filter effect elements take one input in the ``in`` attribute, and +some others take two inputs in the ``in``, ``in2`` attributes. See the +table of elements above for details. + +Filter effect feComponentTransfer +--------------------------------- + +The ``feComponentTransfer`` element can contain children ``feFuncA``, +``feFuncR``, ``feFuncG``, ``feFuncB``, and those all support these +attributes: + +=========== ===== +Attribute Notes +=========== ===== +type +tableValues +slope +intercept +amplitude +exponent +offset +=========== ===== + +CSS features +============ + +Pseudo-classes +-------------- + ++-----------------------------------+-----------------------------------+ +| Pseudo-class | Notes | ++===================================+===================================+ +| :link | | ++-----------------------------------+-----------------------------------+ +| :visited | Because librsvg does not maintain | +| | browser history, this is parsed, | +| | but never matches | ++-----------------------------------+-----------------------------------+ +| :lang() | | ++-----------------------------------+-----------------------------------+ +| :not() | [1]_ | ++-----------------------------------+-----------------------------------+ +| :first-child | [1]_ | ++-----------------------------------+-----------------------------------+ +| :last-child | [1]_ | ++-----------------------------------+-----------------------------------+ +| :only-child | [1]_ | ++-----------------------------------+-----------------------------------+ +| :root | [1]_ | ++-----------------------------------+-----------------------------------+ +| :empty | [1]_ | ++-----------------------------------+-----------------------------------+ +| :nth-child() | [1]_ | ++-----------------------------------+-----------------------------------+ +| :nth-last-child() | [1]_ | ++-----------------------------------+-----------------------------------+ +| :nth-of-type() | [1]_ | ++-----------------------------------+-----------------------------------+ +| :nth-last-of-type() | [1]_ | ++-----------------------------------+-----------------------------------+ +| :first-of-type | [1]_ | ++-----------------------------------+-----------------------------------+ +| :last-of-type | [1]_ | ++-----------------------------------+-----------------------------------+ +| :only-of-type | [1]_ | ++-----------------------------------+-----------------------------------+ + +FIXME: which selectors, combinators, at-rules. + +XML features +============ + +FIXME: ```` + +FIXME: ```` + +FIXME: ``xml:lang`` attribute + +FIXME: ``xml:space`` attribute + +Explicitly Unsupported features +=============================== + +- ``flowRoot`` element and its children - Inkscape, SVG 1.2 only., #13 + +- ``glyph-orientation-horizontal`` property - SVG1.1 only, removed in + SVG2 + +- The pseudo-classes ``:is()`` and ``:where()`` are part of Selectors + Level 4, which is still a working draft. + +Footnotes +========= + +.. [1] + These structural pseudo-classes are implemented in rust-selectors, + which librsvg uses. diff --git a/devel-docs/index.rst b/devel-docs/index.rst index 9d9ea374..b7431dff 100644 --- a/devel-docs/index.rst +++ b/devel-docs/index.rst @@ -6,6 +6,7 @@ Development guide for librsvg :maxdepth: 1 product + features roadmap .. toctree:: @@ -55,6 +56,7 @@ icons and other graphical assets on the desktop. Since then, it has evolved into a few different tools. - :doc:`product` - What comes out of this repository once it is compiled? +- :doc:`features` - Supported elements, attributes, and properties. - :doc:`roadmap` - Ever-changing list of priorities for the maintainers; check this often! -- cgit v1.2.1 From 395811d34245fb8eda225c43c65e3c31d0ea2adc Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 18 Jan 2023 19:36:22 -0600 Subject: README.md: link to the list of features in the devel guide Part-of: --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2e9a76e7..d00ad049 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,9 @@ generate output for printing. Do you want to render non-animated SVGs to a Cairo surface with a minimal API? Librsvg may be adequate for you. -**Supported SVG/CSS features:** Please see the [FEATURES.md](FEATURES.md) file. +**Supported SVG/CSS features:** Please see the chapter for [supported +features](https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/features.html) +in the development guide. ***PLEASE DO NOT SEND PULL REQUESTS TO GITHUB.*** We use [`gitlab.gnome.org`](https://gitlab.gnome.org/GNOME/librsvg) instead. -- cgit v1.2.1 From 1ab400dc16a002709740778fcbc52b3672a5c4fc Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 18 Jan 2023 19:39:04 -0600 Subject: features.rst: Fix headings to not be toplevel ones Part-of: --- devel-docs/features.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/devel-docs/features.rst b/devel-docs/features.rst index 5e5b7df7..9b0a780c 100644 --- a/devel-docs/features.rst +++ b/devel-docs/features.rst @@ -726,10 +726,10 @@ offset =========== ===== CSS features -============ +------------ Pseudo-classes --------------- +~~~~~~~~~~~~~~ +-----------------------------------+-----------------------------------+ | Pseudo-class | Notes | @@ -772,7 +772,7 @@ Pseudo-classes FIXME: which selectors, combinators, at-rules. XML features -============ +------------ FIXME: ```` @@ -783,7 +783,7 @@ FIXME: ``xml:lang`` attribute FIXME: ``xml:space`` attribute Explicitly Unsupported features -=============================== +------------------------------- - ``flowRoot`` element and its children - Inkscape, SVG 1.2 only., #13 @@ -794,7 +794,7 @@ Explicitly Unsupported features Level 4, which is still a working draft. Footnotes -========= +--------- .. [1] These structural pseudo-classes are implemented in rust-selectors, -- cgit v1.2.1 From 35663754cf1be81b1211cb9c1b71771867aa83ae Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 18 Jan 2023 19:57:45 -0600 Subject: features.rst: Fix a few links Part-of: --- devel-docs/features.rst | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/devel-docs/features.rst b/devel-docs/features.rst index 9b0a780c..d21cd07d 100644 --- a/devel-docs/features.rst +++ b/devel-docs/features.rst @@ -1,12 +1,15 @@ SVG and CSS features that librsvg supports ========================================== -Librsvg tries to be a mostly complete renderer for SVG1.1 and SVG2. +Librsvg tries to be a mostly complete renderer for `SVG1.1 +`_ and `SVG2 +`_. -In terms of processing external references, librsvg is a bit more strict -than SVG’s “static mode” and a bit more lenient than “secure static -mode”. See “Security and locations of referenced files” in the reference -documentation for details. +In terms of processing external references, librsvg is a bit more +strict than SVG’s “static mode” and a bit more lenient than “secure +static mode”. See "`Security and locations of referenced files +`_" +in the reference documentation for details. Animation, interactivity, and scripting are not supported. @@ -785,7 +788,7 @@ FIXME: ``xml:space`` attribute Explicitly Unsupported features ------------------------------- -- ``flowRoot`` element and its children - Inkscape, SVG 1.2 only., #13 +- ``flowRoot`` element and its children - Inkscape, SVG 1.2 only. - ``glyph-orientation-horizontal`` property - SVG1.1 only, removed in SVG2 -- cgit v1.2.1 From 579fad2a503d9298a17e03dcfd1e0e10e7a8fc0b Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 18 Jan 2023 20:30:50 -0600 Subject: devel-docs/index.rst: remove obsolete to-do The tour of the code, more or less, is in the Architecture chapter. Part-of: --- devel-docs/index.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/devel-docs/index.rst b/devel-docs/index.rst index b7431dff..4463ba3a 100644 --- a/devel-docs/index.rst +++ b/devel-docs/index.rst @@ -72,8 +72,6 @@ Add basic info on cloning the repo, getting a gitlab account, forking. Understand the code ------------------- -Tour of the code - load a file, render it. - Test suite - move tests/readme here? - `Documentation of the library's internals `_ -- cgit v1.2.1 From 0eaad073feba92f9ef11220614b4d7cd6d34597c Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Wed, 18 Jan 2023 20:53:41 -0600 Subject: Start moving the compilation instruction to the devel guide Part-of: --- COMPILING.md | 73 --------------------------------- configure.ac | 2 +- devel-docs/devel_environment.rst | 88 +++++++++++++++++++++++++++++++++++++--- 3 files changed, 84 insertions(+), 79 deletions(-) diff --git a/COMPILING.md b/COMPILING.md index bee25518..36241cad 100644 --- a/COMPILING.md +++ b/COMPILING.md @@ -23,79 +23,6 @@ can `cargo build` to compile the main user-visible artifact for the * `cargo doc` - will produce the documentation for the Rust crate. -# Installing dependencies for building - -To compile librsvg, you need the following packages installed. The -minimum version is listed here; you may use a newer version instead. - -**Compilers:** - -* a C compiler and `make` tool; we recommend GNU `make`. -* rust 1.63 or later -* cargo - -**Mandatory dependencies:** - -* Cairo 1.16.0 with PNG support -* Freetype2 2.8.0 -* Gdk-pixbuf 2.20.0 -* GIO 2.24.0 -* GObject-Introspection 0.10.8 -* gi-docgen -* python3-docutils -* Libxml2 2.9.0 -* Pango 1.46.0 - -The following sections describe how to install these dependencies on -several systems. - -### Debian based systems - -As of 2018/Feb/22, librsvg cannot be built in `debian stable` and -`ubuntu 18.04`, as they have packages that are too old. - -**Build dependencies on Debian Testing or Ubuntu 18.10:** - -```sh -apt-get install -y gcc make rustc cargo \ -automake autoconf libtool gi-docgen python3-docutils git \ -libgdk-pixbuf2.0-dev libgirepository1.0-dev \ -libxml2-dev libcairo2-dev libpango1.0-dev -``` - -Additionally, as of September 2018 you need to add `gdk-pixbuf` utilities to your path, see #331 for more. - -```sh -PATH="$PATH:/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0" -``` - -### Fedora based systems - -```sh -dnf install -y gcc rust rust-std-static cargo make \ -automake autoconf libtool gi-docgen python3-docutils git redhat-rpm-config \ -gdk-pixbuf2-devel gobject-introspection-devel \ -libxml2-devel cairo-devel cairo-gobject-devel pango-devel -``` - -### openSUSE based systems - -```sh -zypper install -y gcc rust rust-std cargo make \ -automake autoconf libtool python3-gi-docgen python38-docutils git \ -gdk-pixbuf-devel gobject-introspection-devel \ -libxml2-devel cairo-devel pango-devel -``` - -### macOS systems - -Dependencies may be installed using [Homebrew](https://brew.sh) or another -package manager. - -```sh -brew install automake gi-docgen pkgconfig libtool gobject-introspection gdk-pixbuf pango -``` - # Detailed compilation instructions A full build of librsvg requires [autotools]. A full build will produce these: diff --git a/configure.ac b/configure.ac index 7e30c50d..2760ffdd 100644 --- a/configure.ac +++ b/configure.ac @@ -106,7 +106,7 @@ AS_IF(test x$RUSTC = xno, ) dnl MSRV - Minimum Supported Rust Version -dnl If you change this, please update COMPILING.md +dnl If you change this, please update the "_manual_setup" section of devel-docs/devel_environment.rst MINIMUM_RUST_VER=1.63 rust_version=`$RUSTC --version | sed -e 's/^rustc //g'` AX_COMPARE_VERSION([$rust_version],[lt],[$MINIMUM_RUST_VER], [ diff --git a/devel-docs/devel_environment.rst b/devel-docs/devel_environment.rst index d03b5b1f..6ee75b1b 100644 --- a/devel-docs/devel_environment.rst +++ b/devel-docs/devel_environment.rst @@ -13,7 +13,7 @@ System requirements - Around 10 GB free of hard disk space. -- You can either use `podman`_ to work in a +- You can either use `podman `_ to work in a containerized setup (this chapter will show you how), or you can install librsvg's dependencies by hand. @@ -34,9 +34,10 @@ Downloading the source code Setting up with podman ---------------------- -An easy way to set up a development environment is to use `podman`_ to -download and run a container image. This is similar to having a -``chroot`` with all of librsvg's dependencies already set up. +An easy way to set up a development environment is to use `podman +`_ to download and run a container image. This is +similar to having a ``chroot`` with all of librsvg's dependencies +already set up. Install ``podman`` on your distro, and then: @@ -96,7 +97,84 @@ You can now skip to :ref:`build`. Setting up dependencies manually -------------------------------- -FIXME. +To compile librsvg, you need the following packages installed. The +minimum version is listed here; you may use a newer version instead. + +**Compilers and build tools:** + +* a C compiler and `make` tool; we recommend GNU `make`. +* rust 1.63 or later +* cargo +* autoconf, automake, libtool, itstool +* vala (optional) + +**Mandatory dependencies:** + +* Cairo 1.16.0 with PNG support +* Freetype2 2.8.0 +* Gdk-pixbuf 2.20.0 +* GIO 2.24.0 +* GObject-Introspection 0.10.8 +* gi-docgen +* python3-docutils +* Libxml2 2.9.0 +* Pango 1.46.0 + +The following sections describe how to install these dependencies on +several systems. + +Debian based systems +~~~~~~~~~~~~~~~~~~~~ + +As of 2018/Feb/22, librsvg cannot be built in `debian stable` and +`ubuntu 18.04`, as they have packages that are too old. + +**Build dependencies on Debian Testing or Ubuntu 18.10:** + +.. code-block:: sh + + apt-get install -y gcc make rustc cargo \ + automake autoconf libtool gi-docgen python3-docutils git \ + libgdk-pixbuf2.0-dev libgirepository1.0-dev \ + libxml2-dev libcairo2-dev libpango1.0-dev + +Additionally, as of September 2018 you need to add `gdk-pixbuf` +utilities to your path, see `#331 +`_ for details: + +.. code-block:: sh + + PATH="$PATH:/usr/lib/x86_64-linux-gnu/gdk-pixbuf-2.0" + +Fedora based systems +~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: sh + + dnf install -y gcc rust rust-std-static cargo make \ + automake autoconf libtool gi-docgen python3-docutils git redhat-rpm-config \ + gdk-pixbuf2-devel gobject-introspection-devel \ + libxml2-devel cairo-devel cairo-gobject-devel pango-devel + +openSUSE based systems +~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: sh + + zypper install -y gcc rust rust-std cargo make \ + automake autoconf libtool python3-gi-docgen python38-docutils git \ + gdk-pixbuf-devel gobject-introspection-devel \ + libxml2-devel cairo-devel pango-devel + +macOS systems +~~~~~~~~~~~~~ + +Dependencies may be installed using `Homebrew `_ or another +package manager. + +.. code-block:: sh + + brew install automake gi-docgen pkgconfig libtool gobject-introspection gdk-pixbuf pango .. _build: -- cgit v1.2.1 From 50b9230cb2266df346806bc26b161fd2e4267639 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 19 Jan 2023 10:56:03 -0600 Subject: Move the basic compilation instructions from COMPILING.md to the devel guide Part-of: --- COMPILING.md | 22 ---------------------- devel-docs/devel_environment.rst | 10 ++++++++++ 2 files changed, 10 insertions(+), 22 deletions(-) diff --git a/COMPILING.md b/COMPILING.md index 36241cad..ee7e6aa3 100644 --- a/COMPILING.md +++ b/COMPILING.md @@ -1,28 +1,6 @@ Compiling librsvg ================= -**For the impatient:** - -First, install librsvg's dependencies; see ["Installing dependencies for -building"](#installing-dependencies-for-building) below for -instructions for various operating systems. - -For everyday hacking, librsvg looks like a regular Rust project. You -can `cargo build` to compile the main user-visible artifact for the -`rsvg-convert` program: - -* `cargo build --release` - will compile `rsvg-convert` and put it in - `./target/release/rsvg-convert`. You can use that binary directly. - If you need a debug build, use `cargo build --debug` instead; note - that debug binaries run *much* slower! - -* `cargo test` - this runs almost all of librsvg's test suite, which - includes the Rust API and `rsvg-convert`, and is enough for regular - hacking. The full test suite includes tests for the C API; see the - section "Compiling the C API" below. - -* `cargo doc` - will produce the documentation for the Rust crate. - # Detailed compilation instructions A full build of librsvg requires [autotools]. A full build will produce these: diff --git a/devel-docs/devel_environment.rst b/devel-docs/devel_environment.rst index 6ee75b1b..9facbd1f 100644 --- a/devel-docs/devel_environment.rst +++ b/devel-docs/devel_environment.rst @@ -190,6 +190,14 @@ time during regular development. If you are using the podman container as per above, you should do this in the ``/srv/project`` directory most of the time. +To casually test rendering, for example, for a feature you are +developing, you can run `target/debug/rsvg-convert -o output.png +my_test_file.svg`. + +If you do a release build with `carto build --release`, which includes +optimizations, the binary will be in `target/release/rsvg-convert`. +This version is *much* faster than the debug version. + **Doing a full build:** You can use the following: .. code-block:: sh @@ -204,4 +212,6 @@ You should only have to do that if you need to run the full test suite, for the C API tests and the tests for limiting memory consumption. + + .. _podman: https://podman.io/ -- cgit v1.2.1 From 940474732cca606418ab012c889919c4dad61a5c Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 19 Jan 2023 11:13:02 -0600 Subject: index.rst: capitalization Part-of: --- devel-docs/index.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/devel-docs/index.rst b/devel-docs/index.rst index 4463ba3a..4b59aede 100644 --- a/devel-docs/index.rst +++ b/devel-docs/index.rst @@ -2,7 +2,7 @@ Development guide for librsvg ============================= .. toctree:: - :caption: For Distributors and end users + :caption: For Distributors and End Users :maxdepth: 1 product @@ -10,14 +10,14 @@ Development guide for librsvg roadmap .. toctree:: - :caption: Getting started as a Contributor + :caption: Getting Started as a Contributor :maxdepth: 1 devel_environment contributing .. toctree:: - :caption: Understand the code + :caption: Understand the Code :maxdepth: 1 architecture @@ -25,7 +25,7 @@ Development guide for librsvg memory_leaks .. toctree:: - :caption: Design documents + :caption: Design Documents :maxdepth: 1 text_layout -- cgit v1.2.1 From 4bed98e5716ab68016b18f7d8d73d6bdd648ec3e Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 19 Jan 2023 11:20:46 -0600 Subject: product.rst: mention the development guide itself Part-of: --- devel-docs/product.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/devel-docs/product.rst b/devel-docs/product.rst index 4c9d4d3e..092284c7 100644 --- a/devel-docs/product.rst +++ b/devel-docs/product.rst @@ -95,3 +95,7 @@ Other artifacts `_, published online. This is not built from the normal `make` process, but independently as part of the :doc:`ci` pipeline. + +- The rendered HTML version of this development guide. This is not + built from the normal `make` process, but independently as part of + the :doc:`ci` pipeline. -- cgit v1.2.1 From 99fa563d69de2be6a9889ce074c3e92cfd7a86ab Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 19 Jan 2023 11:22:50 -0600 Subject: README.md: mention Matrix, not IRC IRC is deprecated. Part-of: --- README.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d00ad049..1996e7b6 100644 --- a/README.md +++ b/README.md @@ -181,11 +181,12 @@ ways: * [Mail me][mail] at federico@gnome.org. -* IRC: I am `federico` on `irc.gnome.org` in the `#rust` or - `#gnome-hackers` channels. I'm there most weekdays (Mon-Fri) - starting at about UTC 14:00 (that's 08:00 my time; I am in the UTC-6 - timezone). If this is not a convenient time for you, feel free to - [mail me][mail] and we can arrange a time. +* Matrix: I am `@federico` on the [GNOME Hackers][gnome-hackers] and + [Rust ❤️ GNOME][gnome-rust] channels on gnome.org's Matrix. I'm + there most weekdays (Mon-Fri) starting at about UTC 14:00 (that's + 08:00 my time; I am in the UTC-6 timezone). If this is not a + convenient time for you, feel free to [mail me][mail] and we can + arrange a time. [svg]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics [gnome]: https://www.gnome.org/ @@ -203,3 +204,5 @@ ways: [platform]: https://developer.gnome.org/ [guadec-presentation-1]: https://viruta.org/docs/fmq-porting-c-to-rust.pdf [guadec-presentation-2]: https://viruta.org/docs/fmq-refactoring-c-to-rust.pdf +[gnome-hackers]: https://matrix.to/#/#gnome-hackers:gnome.org +[gnome-rust]: https://matrix.to/#/#rust:gnome.org -- cgit v1.2.1 From 9510815ea6f362c4d74bf61b51e8b32ed9ac3795 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 19 Jan 2023 11:31:49 -0600 Subject: Move COMPILING.md to devel-docs/compiling.rst The compilation guide is now in the development guide. Part-of: --- COMPILING.md | 257 ---------------------------------------------- README.md | 12 +-- devel-docs/compiling.rst | 260 +++++++++++++++++++++++++++++++++++++++++++++++ devel-docs/index.rst | 2 + 4 files changed, 268 insertions(+), 263 deletions(-) delete mode 100644 COMPILING.md create mode 100644 devel-docs/compiling.rst diff --git a/COMPILING.md b/COMPILING.md deleted file mode 100644 index ee7e6aa3..00000000 --- a/COMPILING.md +++ /dev/null @@ -1,257 +0,0 @@ -Compiling librsvg -================= - -# Detailed compilation instructions - -A full build of librsvg requires [autotools]. A full build will produce these: - -* `rsvg-convert` binary. -* librsvg shared library with the GObject-based API. -* Gdk-pixbuf loader for SVG files. -* HTML documentation for the GObject-based API, with `gi-docgen`. -* GObject-introspection information for language bindings. -* Vala language bindings. - -Librsvg uses a mostly normal [autotools] setup. The details of how -librsvg integrates Cargo and Rust into its autotools setup are -described in [this blog post][blog], although hopefully you will not -need to refer to it. - -It is perfectly fine to [ask the maintainer][maintainer] if you have -questions about the Autotools setup; it's a tricky bit of machinery, -and we are glad to help. - -There are generic compilation/installation instructions in the -[`INSTALL`][install] file, which comes from Autotools. The following -explains librsvg's peculiarities. - -* [Basic compilation instructions](#basic-compilation-instructions) -* [Verbosity](#verbosity) -* [Debug or release builds](#debug-or-release-builds) -* [Selecting a Rust toolchain](#selecting-a-rust-toolchain) -* [Cross-compilation](#cross-compilation) -* [Building with no network access](#building-with-no-network-access) -* [Running `make distcheck`](#running-make-distcheck) - -# Basic compilation instructions - -If you are compiling a tarball: - -```sh -./configure --enable-vala -make -make install -``` - -See the [`INSTALL`][install] file for details on options you can pass -to the `configure` script to select where to install the compiled -library. - -If you are compiling from a git checkout: - -```sh -./autogen.sh --enable-vala -make -make install -``` - -The `--enable-vala` argument is optional. It will check that you have -the Vala compiler installed. - -# Verbosity - -By default the compilation process is quiet, and it just tells you -which files it is compiling. - -If you wish to see the full compilation command lines, use "`make V=1`" -instead of plain "`make`". - -# Debug or release builds - -Librsvg's artifacts have code both in C and Rust, and each language -has a different way of specifying compilation options to select -compiler optimizations, or whether debug information should be -included. - -* **Rust code:** the librsvg shared library, and the `rsvg-convert` - binary. See below. - -* **C code:** the gdk-pixbuf loader; you should set the `CFLAGS` - environment variable with compiler flags that you want to pass to - the C compiler. - -## Controlling debug or release mode for Rust - -* With a `configure` option: `--enable-debug` or `--disable-debug` -* With an environment variable: `LIBRSVG_DEBUG=yes` or `LIBRSVG_DEBUG=no` - -For the Rust part of librsvg, we have a flag that -you can pass at `configure` time. When enabled, the Rust -sub-library will have debugging information and no compiler -optimizations. **This flag is off by default:** if the flag is not -specified, the Rust sub-library will be built in release mode (no -debug information, full compiler optimizations). - -The rationale is that people who already had scripts in place to build -binary packages for librsvg, generally from release tarballs, are -already using conventional machinery to specify C compiler options, -such as that in RPM specfiles or Debian source packages. However, -they may not contemplate Rust libraries and they will certainly -not want to modify their existing packaging scripts too much. - -So, by default, the Rust library builds in **release mode**, to make -life easier to binary distributions. Librsvg's build scripts will add -`--release` to the Cargo command line by default. - -Developers can request a debug build of the Rust code by -passing `--enable-debug` to the `configure` script, or by setting the -`LIBRSVG_DEBUG=yes` environment variable before calling `configure`. -This will omit the `--release` option from Cargo, so that it will -build the Rust sub-library in debug mode. - -In case both the environment variable and the command-line option are -specified, the command-line option overrides the env var. - -# Selecting a Rust toolchain - -By default, the configure/make steps will use the `cargo` binary that -is found in your `$PATH`. If you have a system installation of Rust -and one in your home directory, or for special build systems, you may -need to override the locations of `cargo` and/or `rustc`. In this -case, you can set any of these environment variables before running -`configure` or `autogen.sh`: - -* `RUSTC` - path to the `rustc` compiler -* `CARGO` - path to `cargo` - -Note that `$RUSTC` only gets used in the `configure` script to ensure -that there is a Rust compiler installed with an appropriate version. -The actual compilation process just uses `$CARGO`, and assumes that -that `cargo` binary will use the same Rust compiler as the other -variable. - -# Cross-compilation - -If you need to cross-compile librsvg, specify the `--host=TRIPLE` to -the `configure` script as usual with Autotools. This will cause -librsvg's build scripts to automatically pass `--target=TRIPLE` to -`cargo`. - -Note, however, that Rust may support different targets than the C -compiler on your system. Rust's supported targets can be found in the -[rustc manual](https://doc.rust-lang.org/nightly/rustc/platform-support.html) - -You can check Jorge Aparicio's [guide on cross-compilation for -Rust][rust-cross] for more details. - -## Overriding the Rust target name - -If you need `cargo --target=FOO` to obtain a different value from the -one you specified for `--host=TRIPLE`, you can use the `RUST_TARGET` -variable, and this will be passed to `cargo`. For example, - -```sh -RUST_TARGET=aarch64-unknown-linux-gnu ./configure --host=aarch64-buildroot-linux-gnu -# will run "cargo --target=aarch64-unknown-linux-gnu" for the Rust part -``` - -## Cross-compiling to a target not supported by Rust out of the box - -When building with a target that is not supported out of the box by -Rust, you have to do this: - -1. Create a [target JSON definition file][target-json]. - -2. Set the environment variable `RUST_TARGET_PATH` to its directory - for the `make` command. - -Example: - -```sh -cd /my/target/definition -echo "JSON goes here" > MYMACHINE-VENDOR-OS.json -cd /source/tree/for/librsvg -./configure --host=MYMACHINE-VENDOR-OS -make RUST_TARGET_PATH=/my/target/definition -``` - -## Cross-compiling for win32 target - -You can also cross-compile to win32 (Microsoft Windows) target by using -[MinGW-w64][mingw-w64]. You need to specify the appropriate target in the same way -as usual: - -* Set an appropriate target via the `--host` configure option: - * `i686-w64-mingw32` for 32-bit target - * `x86_64-w64-mingw32` for 64-bit target -* Set an appropriate RUST_TARGET: - * `i686-pc-windows-gnu` for 32-bit target - * `x86_64-pc-windows-gnu` for 64-bit target - -In addition you may need to link with some win32 specific libraries like -`LIBS="-lws2_32 -luserenv"`. - -Example: - -```sh -./configure \ - --host=x86_64-w64-mingw32 \ - RUST_TARGET=x86_64-pc-windows-gnu \ - LIBS="-lws2_32 -luserenv" -make -``` - -The most painful aspect of this way of building is preparing a win32 -build for each of librsvg's dependencies. [MXE][mxe] may help you on -this work. - - - -# Building with no network access - -Automated build systems generally avoid network access so that they -can compile from known-good sources, instead of pulling random updates -from the net every time. However, normally Cargo likes to download -dependencies when it first compiles a Rust project. - -We use [`cargo vendor`][cargo-vendor] to ship librsvg release tarballs -with the source code for Rust dependencies **embedded within the -tarball**. If you unpack a librsvg tarball, these sources will appear -in the `vendor/` subdirectory. If you build librsvg from a -tarball, instead of git, it should not need to access the network to -download extra sources at all. - -Build systems can use [Cargo's source replacement -mechanism][cargo-source-replacement] to override the location of the -source code for the Rust dependencies, for example, in order to patch -one of the Rust crates that librsvg uses internally. - -The source replacement information is in `rust/.cargo/config` in the -unpacked tarball. Your build system can patch this file as needed. - -# Running `make distcheck` - -The `make distcheck` command will built a release tarball, extract it, -compile it and test it. However, part of the `make install` process -within that command will try to install the gdk-pixbuf loader in your -system location, and it will fail. - -Please run `make distcheck` like this: - -``` -$ make distcheck DESTDIR=/tmp/foo -``` - -That `DESTDIR` will keep the gdk-pixbuf loader installation from -trying to modify your system locations. - -[autotools]: https://autotools.io/index.html -[blog]: https://people.gnome.org/~federico/blog/librsvg-build-infrastructure.html -[maintainer]: README.md#maintainers -[install]: INSTALL -[cargo-vendor]: https://crates.io/crates/cargo-vendor -[cargo-source-replacement]: http://doc.crates.io/source-replacement.html -[rust-cross]: https://github.com/japaric/rust-cross -[target-json]: https://github.com/japaric/rust-cross#target-specification-files -[mingw-w64]: https://mingw-w64.org/ -[mxe]: https://mxe.cc/ diff --git a/README.md b/README.md index 1996e7b6..01a213f5 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,7 @@ may run into some peculiarities due to the Rust internals library if you are **cross-compiling** or if you are in a **build system with no network access**, or if you are **building binary packages from a librsvg tarball**. In those cases, please refer to the -[`COMPILING.md`][compiling] file. +[Detailed compilation instructions][compiling] in the development guide. **Documentation:** You can read the documentation for librsvg's [C API][c-docs] or the [Rust API][rust-docs]. Please [file an @@ -77,10 +77,9 @@ documentation for information on how to load the `Rsvg` namespace. There is a code of conduct for contributors to librsvg; please see the file [`code-of-conduct.md`][coc]. -Please see the [Development guide for -librsvg](https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/index.html) -on how to contribute to librsvg, how set up your development -environment, and for a description of librsvg's architecture. +Please see the [Development guide for librsvg][devel-guide] on how to +contribute to librsvg, how set up your development environment, and +for a description of librsvg's architecture. For information on how to report bugs, or how to contribute to librsvg in general, please see the file [`CONTRIBUTING.md`][contributing]. @@ -193,7 +192,7 @@ ways: [cairo]: https://www.cairographics.org/ [coc]: code-of-conduct.md [autotools]: https://autotools.io/index.html -[compiling]: COMPILING.md +[compiling]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/compiling.html [mail]: mailto:federico@gnome.org [bugs]: https://gitlab.gnome.org/GNOME/librsvg/issues [gi]: https://wiki.gnome.org/Projects/GObjectIntrospection @@ -206,3 +205,4 @@ ways: [guadec-presentation-2]: https://viruta.org/docs/fmq-refactoring-c-to-rust.pdf [gnome-hackers]: https://matrix.to/#/#gnome-hackers:gnome.org [gnome-rust]: https://matrix.to/#/#rust:gnome.org +[devel-guide]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/index.html diff --git a/devel-docs/compiling.rst b/devel-docs/compiling.rst new file mode 100644 index 00000000..07ba2e62 --- /dev/null +++ b/devel-docs/compiling.rst @@ -0,0 +1,260 @@ +Detailed compilation instructions +================================= + +A full build of librsvg requires +`autotools `__. A full build will +produce these (see :doc:`product` for details): + +- ``rsvg-convert`` binary and its ``man`` page. +- librsvg shared library with the GObject-based API. +- Gdk-pixbuf loader for SVG files. +- HTML documentation for the GObject-based API, with ``gi-docgen``. +- GObject-introspection information for language bindings. +- Vala language bindings. + +Librsvg uses a mostly normal `autotools +`__ setup. The historical details of +how librsvg integrates Cargo and Rust into its autotools setup are +described in `this blog post +`__, +although hopefully you will not need to refer to it. + +It is perfectly fine to `ask the maintainer +`__ if you have +questions about the Autotools setup; it’s a tricky bit of machinery, and +we are glad to help. + +The rest of this document explains librsvg’s peculiarities apart from +the usual way of compiling Autotools projects: + +- `Basic compilation instructions <#basic-compilation-instructions>`__ +- `Verbosity <#verbosity>`__ +- `Debug or release builds <#debug-or-release-builds>`__ +- `Selecting a Rust toolchain <#selecting-a-rust-toolchain>`__ +- `Cross-compilation <#cross-compilation>`__ +- `Building with no network + access <#building-with-no-network-access>`__ +- `Running "make distcheck" <#running-make-distcheck>`__ + +Basic compilation instructions +------------------------------ + +If you are compiling a tarball: + +.. code:: sh + + ./configure --enable-gtk-doc --enable-vala + make + make install + +See the ``INSTALL`` file for details on options you can +pass to the ``configure`` script to select where to install the compiled +library. + +If you are compiling from a git checkout: + +.. code:: sh + + ./autogen.sh --enable-gtk-doc --enable-vala + make + make install + +The ``--enable-gtk-doc`` and ``--enable-vala`` arguments are +optional. They will check that you have gi-docgen and the Vala compiler +installed, respectively. + +Verbosity +--------- + +By default the compilation process is quiet, and it just tells you which +files it is compiling. + +If you wish to see the full compilation command lines, use +“``make V=1``” instead of plain “``make``”. + +Debug or release builds +----------------------- + +Librsvg’s artifacts have code both in C and Rust, and each language has +a different way of specifying compilation options to select compiler +optimizations, or whether debug information should be included. + +- **Rust code:** the librsvg shared library, and the ``rsvg-convert`` + binary. See below. + +- **C code:** the gdk-pixbuf loader; you should set the ``CFLAGS`` + environment variable with compiler flags that you want to pass to the + C compiler. + +Controlling debug or release mode for Rust +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +- With a ``configure`` option: ``--enable-debug`` or + ``--disable-debug`` +- With an environment variable: ``LIBRSVG_DEBUG=yes`` or + ``LIBRSVG_DEBUG=no`` + +For the Rust part of librsvg, we have a flag that you can pass at +``configure`` time. When enabled, the Rust sub-library will have +debugging information and no compiler optimizations. **This flag is off +by default:** if the flag is not specified, the Rust sub-library will be +built in release mode (no debug information, full compiler +optimizations). + +The rationale is that people who already had scripts in place to build +binary packages for librsvg, generally from release tarballs, are +already using conventional machinery to specify C compiler options, such +as that in RPM specfiles or Debian source packages. However, they may +not contemplate Rust libraries and they will certainly not want to +modify their existing packaging scripts too much. + +So, by default, the Rust library builds in **release mode**, to make +life easier to binary distributions. Librsvg’s build scripts will add +``--release`` to the Cargo command line by default. + +Developers can request a debug build of the Rust code by passing +``--enable-debug`` to the ``configure`` script, or by setting the +``LIBRSVG_DEBUG=yes`` environment variable before calling ``configure``. +This will omit the ``--release`` option from Cargo, so that it will +build the Rust sub-library in debug mode. + +In case both the environment variable and the command-line option are +specified, the command-line option overrides the env var. + +Selecting a Rust toolchain +-------------------------- + +By default, the configure/make steps will use the ``cargo`` binary that +is found in your ``$PATH``. If you have a system installation of Rust +and one in your home directory, or for special build systems, you may +need to override the locations of ``cargo`` and/or ``rustc``. In this +case, you can set any of these environment variables before running +``configure`` or ``autogen.sh``: + +- ``RUSTC`` - path to the ``rustc`` compiler +- ``CARGO`` - path to ``cargo`` + +Note that ``$RUSTC`` only gets used in the ``configure`` script to +ensure that there is a Rust compiler installed with an appropriate +version. The actual compilation process just uses ``$CARGO``, and +assumes that that ``cargo`` binary will use the same Rust compiler as +the other variable. + +Cross-compilation +----------------- + +If you need to cross-compile librsvg, specify the ``--host=TRIPLE`` to +the ``configure`` script as usual with Autotools. This will cause +librsvg’s build scripts to automatically pass ``--target=TRIPLE`` to +``cargo``. + +Note, however, that Rust may support different targets than the C +compiler on your system. Rust’s supported targets can be found in the +`rustc +manual `__ + +You can check Jorge Aparicio’s `guide on cross-compilation for +Rust `__ for more details. + +Overriding the Rust target name +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you need ``cargo --target=FOO`` to obtain a different value from the +one you specified for ``--host=TRIPLE``, you can use the ``RUST_TARGET`` +variable, and this will be passed to ``cargo``. For example, + +.. code:: sh + + RUST_TARGET=aarch64-unknown-linux-gnu ./configure --host=aarch64-buildroot-linux-gnu + # will run "cargo --target=aarch64-unknown-linux-gnu" for the Rust part + +Cross-compiling to a target not supported by Rust out of the box +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When building with a target that is not supported out of the box by +Rust, you have to do this: + +1. Create a `target JSON definition + file `__. + +2. Set the environment variable ``RUST_TARGET_PATH`` to its directory + for the ``make`` command. + +Example: + +.. code:: sh + + cd /my/target/definition + echo "JSON goes here" > MYMACHINE-VENDOR-OS.json + cd /source/tree/for/librsvg + ./configure --host=MYMACHINE-VENDOR-OS + make RUST_TARGET_PATH=/my/target/definition + +Cross-compiling for win32 target +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can also cross-compile to win32 (Microsoft Windows) target by using +`MinGW-w64 `__. You need to specify the +appropriate target in the same way as usual: + +- Set an appropriate target via the ``--host`` configure option: + + - ``i686-w64-mingw32`` for 32-bit target + - ``x86_64-w64-mingw32`` for 64-bit target + +- Set an appropriate RUST_TARGET: + + - ``i686-pc-windows-gnu`` for 32-bit target + - ``x86_64-pc-windows-gnu`` for 64-bit target + +In addition you may need to link with some win32 specific libraries like +``LIBS="-lws2_32 -luserenv"``. + +Example: + +.. code:: sh + + ./configure \ + --host=x86_64-w64-mingw32 \ + RUST_TARGET=x86_64-pc-windows-gnu \ + LIBS="-lws2_32 -luserenv" + make + +The most painful aspect of this way of building is preparing a win32 +build for each of librsvg’s dependencies. `MXE `__ may +help you on this work. + +Building with no network access +------------------------------- + +Automated build systems generally avoid network access so that they can +compile from known-good sources, instead of pulling random updates from +the net every time. However, normally Cargo likes to download +dependencies when it first compiles a Rust project. + +You can use `cargo vendor +`_ to +download librsvg's Rust dependencies ahead of time, so that subsequent +compilation don't require network access. + +Build systems can use `Cargo’s source replacement +mechanism `_ to override +the location of the source code for the Rust dependencies, for example, +in order to patch one of the Rust crates that librsvg uses internally. + +Running ``make distcheck`` +-------------------------- + +The ``make distcheck`` command will built a release tarball, extract it, +compile it and test it. However, part of the ``make install`` process +within that command will try to install the gdk-pixbuf loader in your +system location, and it will fail. + +Please run ``make distcheck`` like this: + +:: + + $ make distcheck DESTDIR=/tmp/foo + +That ``DESTDIR`` will keep the gdk-pixbuf loader installation from +trying to modify your system locations. diff --git a/devel-docs/index.rst b/devel-docs/index.rst index 4b59aede..97e5e724 100644 --- a/devel-docs/index.rst +++ b/devel-docs/index.rst @@ -8,6 +8,7 @@ Development guide for librsvg product features roadmap + compiling .. toctree:: :caption: Getting Started as a Contributor @@ -59,6 +60,7 @@ evolved into a few different tools. - :doc:`features` - Supported elements, attributes, and properties. - :doc:`roadmap` - Ever-changing list of priorities for the maintainers; check this often! +- :doc:`compiling` - cross compilation, debug/release builds, special options. Getting started --------------- -- cgit v1.2.1 From 08da2b2a136f18a9f48fd0a7980770464ae2d623 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 19 Jan 2023 11:49:11 -0600 Subject: Move SECURITY.md to devel-docs/security.rst The security chapter is now in the development guide. Part-of: --- README.md | 6 ++ SECURITY.md | 195 ------------------------------------------- devel-docs/index.rst | 5 +- devel-docs/security.rst | 216 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 226 insertions(+), 196 deletions(-) delete mode 100644 SECURITY.md create mode 100644 devel-docs/security.rst diff --git a/README.md b/README.md index 01a213f5..c6445d58 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,11 @@ Introspection][gi]. This way, it is available in many programming languages other than C. Please see your language binding's documentation for information on how to load the `Rsvg` namespace. +**Security:** For a list of releases with security issues, +instructions on reporting security-related bugs, and the security +considerations for librsvg's dependencies, see the [Security +chapter][security] in the development guide. + [c-docs]: https://gnome.pages.gitlab.gnome.org/librsvg/Rsvg-2.0/index.html [rust-docs]: https://gnome.pages.gitlab.gnome.org/librsvg/doc/librsvg/index.html @@ -206,3 +211,4 @@ ways: [gnome-hackers]: https://matrix.to/#/#gnome-hackers:gnome.org [gnome-rust]: https://matrix.to/#/#rust:gnome.org [devel-guide]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/index.html +[security]: https://gnome.pages.gitlab.gnome.org/librsvg/devel-docs/security.html diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index f9ae8781..00000000 --- a/SECURITY.md +++ /dev/null @@ -1,195 +0,0 @@ -# Reporting security bugs - -Please mail the maintainer at federico@gnome.org. You can use the GPG -public key from https://viruta.org/docs/fmq-gpg.asc to send encrypted -mail. - -# Librsvg releases with security fixes - -Librsvg releases have a version number like major.minor.micro. Note -that releases with an odd minor number (e.g. 2.47.x since 47 is odd) -are considered development releases and should not be used in -production systems. - -The following list is only for stable release streams, where the minor -number is even (e.g. 2.50.x). - -### 2.50.4 - -RUSTSEC-2020-0146 - lifetime erasure in generic-array. - -### 2.48.10 - -CVE-2020-35905 - RUSTSEC-2020-0059 - data race in futures-util. - -CVE-2020-35906 - RUSTSEC-2020-0060 - use-after-free in futures-task. - -CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec. - -RUSTSEC-2020-0146 - lifetime erasure in generic-array. - -### 2.48.0 - -CVE-2019-20446 - guard against exponential growth of CPU time -from malicious SVGs. - -### 2.46.5 - -RUSTSEC-2020-0146 - lifetime erasure in generic-array. - -CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec. - -See notes below on libcroco. - -### 2.44.17 - -RUSTSEC-2020-0146 - lifetime erasure in generic-array. - -CVE-2019-15554 - RUSTSEC-2019-0012 - memory corruption in smallvec. - -CVE-2019-15551 - RUSTSEC-2019-0009 - double-free and use-after-free in smallvec. - -CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec. - -See notes below on libcroco. - -### 2.44.16 - -CVE-2019-20446 - guard against exponential growth of CPU time -from malicious SVGs. - -See notes below on libcroco. - -### 2.42.8 - -CVE-2019-20446 - guard against exponential growth of CPU time -from malicious SVGs. - -See notes below on libcroco. - -### 2.42.9 - -CVE-2018-20991 - RUSTSEC-2018-0003 - double-free in smallvec. - -See notes below on libcroco. - -### 2.40.21 - -CVE-2019-20446 - guard against exponential growth of CPU time -from malicious SVGs. - -See notes below on libcroco. - -### 2.40.18 - -CVE-2017-11464 - Fix division-by-zero in the Gaussian blur code. - -See notes below on libcroco. - -### Earlier releases should be avoided and are not listed here. - -**Important note on libcroco:** Note that librsvg 2.46.x and earlier use -[libcroco](https://gitlab.gnome.org/Archive/libcroco/) for parsing -CSS, but that library is deprecated, unmaintained, and has open CVEs as -of May 2021. - -If your application processes untrusted data, please avoid using -librsvg 2.46.x or earlier. The first release of librsvg that does not -use libcroco is 2.48.0. - -# Librsvg's dependencies - -Librsvg depends on the following libraries implemented in memory-unsafe languages: - -* **libxml2** - loading XML data. -* **cairo** - 2D rendering engine. -* **gdk-pixbuf** - decoding raster images like JPEG/PNG. -* **freetype2** - font renderer. -* **harfbuzz** - text shaping engine. - -And of course, their recursive dependencies as well, such as **glib/gio**. - -## Security considerations for libxml2 - -Librsvg uses the following configuration for the SAX2 parser in libxml2: - - * `XML_PARSE_NONET` - forbid network access. - * `XML_PARSE_BIG_LINES` - store big line numbers. - -As a special case, librsvg enables `replaceEntities` in the -`_xmlParserCtxtPtr` struct so that libxml2 will expand references only -to internal entities declared in the DTD subset. External entities -are disabled. - -For example, the following document renders two rectangles that are -expanded from internal entities: - -``` -"> - "> -]> - - &Rect1; - &Rect2; - -``` - -However, an external entity like - -``` - -``` - -will generate an XML parse error and the document will not be loaded. - -## Security considerations for Cairo - -Cairo is easy to crash if given coordinates that fall outside the -range of its 24.8 fixed-point numbers. Librsvg is working on -mitigating this. - -## Security considerations for gdk-pixbuf - -Gdk-pixbuf depends on **libpng**, **libjpeg**, and other libraries for -different image formats. - -# Security considerations for librsvg - -**Built-in limits:** Librsvg has built-in limits for the following: - -* Limit on the maximum number of loaded XML elements, set to 1,000,000 - (one million). SVG documents with more than this number of elements - will fail to load. This is a mitigation for malicious documents - that would otherwise consume large amounts of memory, for example by - including a huge number of `` elements with no useful content. - This is set in the file `src/limits.rs` in the `MAX_LOADED_ELEMENTS` - constant. - -* Limit on the maximum number of referenced elements while rendering. - The `` element in SVG and others like `` can reference - other elements in the document. Malicious documents can cause an - exponential number of references to be resolved, so librsvg places a - limit of 500,000 references (half a million) to avoid unbounded - consumption of CPU time. This is set in the file `src/limits.rs` in - the `MAX_REFERENCED_ELEMENTS` constant. - -Librsvg has no built-in limits on the total amount of memory or CPU -time consumed to process a document. Your application may want to -place limits on this, especially if it processes untrusted SVG -documents. - -**Processing external files:** Librsvg processes references to -external files by itself: XML XInclude, `xlink:href` attributes, etc. -Please see the section "Security and locations of referenced files" in -the [developer's -documentation](https://developer-old.gnome.org/rsvg/unstable/RsvgHandle.html) -to see what criteria is used to accept or reject a file based on its -location. If your application has more stringent requirements, it may -need to sandbox its use of librsvg. - -**SVG features:** Librsvg ignores animations, scripts, and events -declared in SVG documents. It always handles referenced images, -similar to SVG's [static processing -mode](https://www.w3.org/TR/SVG2/conform.html#static-mode). - diff --git a/devel-docs/index.rst b/devel-docs/index.rst index 97e5e724..856a3920 100644 --- a/devel-docs/index.rst +++ b/devel-docs/index.rst @@ -9,6 +9,7 @@ Development guide for librsvg features roadmap compiling + security .. toctree:: :caption: Getting Started as a Contributor @@ -60,7 +61,9 @@ evolved into a few different tools. - :doc:`features` - Supported elements, attributes, and properties. - :doc:`roadmap` - Ever-changing list of priorities for the maintainers; check this often! -- :doc:`compiling` - cross compilation, debug/release builds, special options. +- :doc:`compiling` - Cross compilation, debug/release builds, special options. +- :doc:`security` - Reporting security bugs, releases with security + fixes, security of dependencies. Getting started --------------- diff --git a/devel-docs/security.rst b/devel-docs/security.rst new file mode 100644 index 00000000..95b2f749 --- /dev/null +++ b/devel-docs/security.rst @@ -0,0 +1,216 @@ +Security +======== + +Reporting security bugs +----------------------- + +Please mail the maintainer at federico@gnome.org. You can use the GPG +public key from https://viruta.org/docs/fmq-gpg.asc to send encrypted +mail. + +Librsvg releases with security fixes +------------------------------------ + +Librsvg releases have a version number like major.minor.micro. Note that +releases with an odd minor number (e.g. 2.47.x since 47 is odd) are +considered development releases and should not be used in production +systems. + +The following list is only for stable release streams, where the minor +number is even (e.g. 2.50.x). + +2.50.4 +~~~~~~ + +RUSTSEC-2020-0146 - lifetime erasure in generic-array. + +2.48.10 +~~~~~~~ + +CVE-2020-35905 - RUSTSEC-2020-0059 - data race in futures-util. + +CVE-2020-35906 - RUSTSEC-2020-0060 - use-after-free in futures-task. + +CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec. + +RUSTSEC-2020-0146 - lifetime erasure in generic-array. + +2.48.0 +~~~~~~ + +CVE-2019-20446 - guard against exponential growth of CPU time from +malicious SVGs. + +2.46.5 +~~~~~~ + +RUSTSEC-2020-0146 - lifetime erasure in generic-array. + +CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec. + +See notes below on libcroco. + +2.44.17 +~~~~~~~ + +RUSTSEC-2020-0146 - lifetime erasure in generic-array. + +CVE-2019-15554 - RUSTSEC-2019-0012 - memory corruption in smallvec. + +CVE-2019-15551 - RUSTSEC-2019-0009 - double-free and use-after-free in +smallvec. + +CVE-2021-25900 - RUSTSEC-2021-0003 - buffer overflow in smallvec. + +See notes below on libcroco. + +2.44.16 +~~~~~~~ + +CVE-2019-20446 - guard against exponential growth of CPU time from +malicious SVGs. + +See notes below on libcroco. + +2.42.8 +~~~~~~ + +CVE-2019-20446 - guard against exponential growth of CPU time from +malicious SVGs. + +See notes below on libcroco. + +2.42.9 +~~~~~~ + +CVE-2018-20991 - RUSTSEC-2018-0003 - double-free in smallvec. + +See notes below on libcroco. + +2.40.21 +~~~~~~~ + +CVE-2019-20446 - guard against exponential growth of CPU time from +malicious SVGs. + +See notes below on libcroco. + +2.40.18 +~~~~~~~ + +CVE-2017-11464 - Fix division-by-zero in the Gaussian blur code. + +See notes below on libcroco. + +Earlier releases should be avoided and are not listed here. +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Important note on libcroco:** Note that librsvg 2.46.x and earlier use +`libcroco `__ for parsing +CSS, but that library is deprecated, unmaintained, and has open CVEs as +of May 2021. + +If your application processes untrusted data, please avoid using librsvg +2.46.x or earlier. The first release of librsvg that does not use +libcroco is 2.48.0. + +Librsvg’s dependencies +---------------------- + +Librsvg depends on the following libraries implemented in memory-unsafe +languages: + +- **libxml2** - loading XML data. +- **cairo** - 2D rendering engine. +- **gdk-pixbuf** - decoding raster images like JPEG/PNG. +- **freetype2** - font renderer. +- **harfbuzz** - text shaping engine. + +And of course, their recursive dependencies as well, such as +**glib/gio**, **libjpeg**, **libpng**. + +Security considerations for libxml2 +----------------------------------- + +Librsvg uses the following configuration for the SAX2 parser in libxml2: + +- ``XML_PARSE_NONET`` - forbid network access. +- ``XML_PARSE_BIG_LINES`` - store big line numbers. + +As a special case, librsvg enables ``replaceEntities`` in the +``_xmlParserCtxtPtr`` struct so that libxml2 will expand references only +to internal entities declared in the DTD subset. External entities are +disabled. + +For example, the following document renders two rectangles that are +expanded from internal entities: + +:: + + "> + "> + ]> + + &Rect1; + &Rect2; + + +However, an external entity like + +:: + + + +will generate an XML parse error and the document will not be loaded. + +Security considerations for Cairo +--------------------------------- + +Cairo is easy to crash if given coordinates that fall outside the range +of its 24.8 fixed-point numbers. Librsvg is working on mitigating this. + +Security considerations for gdk-pixbuf +-------------------------------------- + +Gdk-pixbuf depends on **libpng**, **libjpeg**, and other libraries for +different image formats. + +Security considerations for librsvg +=================================== + +**Built-in limits:** Librsvg has built-in limits for the following: + +- Limit on the maximum number of loaded XML elements, set to 1,000,000 + (one million). SVG documents with more than this number of elements + will fail to load. This is a mitigation for malicious documents that + would otherwise consume large amounts of memory, for example by + including a huge number of ```` elements with no useful content. + This is set in the file ``src/limits.rs`` in the + ``MAX_LOADED_ELEMENTS`` constant. + +- Limit on the maximum number of referenced elements while rendering. + The ```` element in SVG and others like ```` can + reference other elements in the document. Malicious documents can + cause an exponential number of references to be resolved, so librsvg + places a limit of 500,000 references (half a million) to avoid + unbounded consumption of CPU time. This is set in the file + ``src/limits.rs`` in the ``MAX_REFERENCED_ELEMENTS`` constant. + +Librsvg has no built-in limits on the total amount of memory or CPU time +consumed to process a document. Your application may want to place +limits on this, especially if it processes untrusted SVG documents. + +**Processing external files:** Librsvg processes references to +external files by itself: XML XInclude, ``xlink:href`` attributes, +etc. Please see the section "`Security and locations of referenced +files +`_" +in the reference documentation to see what criteria are used to accept +or reject a file based on its location. If your application has more +stringent requirements, it may need to sandbox its use of librsvg. + +**SVG features:** Librsvg ignores animations, scripts, and events +declared in SVG documents. It always handles referenced images, similar +to SVG’s `static processing +mode `__. -- cgit v1.2.1 From d9744a5e101cafb67cd85f0acdb64397e5800a02 Mon Sep 17 00:00:00 2001 From: Federico Mena Quintero Date: Thu, 19 Jan 2023 11:49:40 -0600 Subject: Makefile.am: remove Markdown documents that are now in the devel guide Part-of: --- Makefile.am | 2 -- 1 file changed, 2 deletions(-) diff --git a/Makefile.am b/Makefile.am index 3c6388c9..af2e6514 100644 --- a/Makefile.am +++ b/Makefile.am @@ -243,7 +243,6 @@ CLEANFILES += rsvg-convert.1 endif dist_doc_DATA = \ - COMPILING.md \ CONTRIBUTING.md \ README.md \ code-of-conduct.md @@ -255,7 +254,6 @@ EXTRA_DIST = \ AUTHORS \ COPYING.LIB \ NEWS \ - SECURITY.md \ Rsvg-2.0-custom.vala \ Rsvg-2.0.metadata \ glib-tap.mk \ -- cgit v1.2.1