�ɲɾ�����ӯ�����һ��ˣ��������С���˴��ͣ�������P���ҹ��ñ˽��ά�Բ��������˸߸ԣ�������ơ��ҹ��ñ�����ά�Բ���ˡ���˳^�ӣ������ӡ� ���ͯj�ӣ��ƺ���ӣ� ? PNG ?%k25u25%fgd5n!? PNG ?%k25u25%fgd5n!? PNG ?%k25u25%fgd5n!? PNG ?%k25u25%fgd5n!PKs1]ã^dÏ&& README.mdnu„[µü¤Librsvg ======= This is librsvg - A small library to render Scalable Vector Graphics ([SVG][svg]), associated with the [GNOME Project][gnome]. It renders SVG files to [Cairo][cairo] surfaces. Cairo is the 2D, antialiased drawing library that GNOME uses to draw things to the screen or to 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. ***GITHUB WILL DELETE YOUR PULL REQUESTS!*** We use [`gitlab.gnome.org`](https://gitlab.gnome.org/GNOME/librsvg) instead. Please see [`CONTRIBUTING.md`][contributing] for details. Using librsvg ------------- **Compiling:** Librsvg uses a mostly normal [autotools] setup. You 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. **Documentation:** You can read the [documentation for librsvg][docs] at developer.gnome.org. Please [tell us][mail] if you don't find something there that you need. **Bug tracking:** If you have found a bug, take a look at [our bug tracker][bugs]. Please see the "[reporting bugs][reporting-bugs]" section in the file [CONTRIBUTING.md][contributing] to see how to provide a good bug report. **Asking questions:** Feel free to ask questions about using librsvg in the [desktop-devel-list][d-d-l] mailing list. **Programming languages:** Librsvg exports its API through [GObject 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. Contributing to librsvg's development ------------------------------------- There is a code of conduct for contributors to librsvg; please see the file [`code-of-conduct.md`][coc]. For information on how to report bugs, or how to contribute to librsvg in general, please see the file [`CONTRIBUTING.md`][contributing]. Goals of librsvg ---------------- Librsvg aims to be a low-footprint library for rendering SVG images. It is used primarily in the [GNOME project](https://www.gnome.org) to render SVG icons and vector images that appear on the desktop. It is also used in Wikimedia to render the SVG images that appear in Wikipedia, so that even old web browsers can display them. Many projects which casually need to render static SVG images use librsvg. We aim to be a "render this SVG for me, quickly, and with a minimal API" kind of library. Feature additions will be considered on a case-by-case basis. Non-goals of librsvg -------------------- We don't aim to: * Implement every single SVG feature that is in the spec. * Implement scripting or external access to the SVG's DOM. * Implement support for CSS-based animations (but if you can think of a nice API to do this, we would be glad to know!) * Replace the industrial-strength SVG rendering machinery in modern web browsers. Of course, [contributions are welcome][contributing]. In particular, if you find nice ways of doing the above while still maintaining the existing API of librsvg, we would love to know about it! Who uses librsvg? ----------------- Librsvg is part of the [GNOME platform][platform]. Inside GNOME, librsvg takes multiple roles: * Loads SVGs from the generic gdk-pixbuf loader infrastructure, so any application which uses gdk-pixbuf can load SVGs as if they were raster images. * Loads SVG icons for the desktop. * Creates SVG thumbnails for the file manager. * Loads SVGs within GNOME's default image viewer, Eye of Gnome. Outside of GNOME's core: * GNOME games (chess, five-or-more, etc. to draw game pieces) * GIMP * GCompris * Claws-mail * Darktable * Mate-panel * Evas/Enlightenment * Emacs * ImageMagick * Wikipedia, to render SVGs as raster images for old browsers. *Special thanks to Wikimedia for providing excellent bug reports.* Presentations on librsvg ------------------------ "[Replacing C library code with Rust: What I learned with librsvg][guadec-presentation]" was presented at GUADEC 2017. It gives a little history of librsvg, and how/why it is being ported to Rust from C. Maintainers ----------- The maintainer of librsvg is [Federico Mena Quintero][federico]. Feel free to contact me for any questions you may have about librsvg, both its usage and its development. You can contact me in the following 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. [svg]: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics [gnome]: https://www.gnome.org/ [cairo]: https://www.cairographics.org/ [coc]: code-of-conduct.md [autotools]: https://autotools.io/index.html [compiling]: COMPILING.md [docs]: https://developer.gnome.org/rsvg/stable/ [mail]: mailto:federico@gnome.org [bugs]: https://gitlab.gnome.org/GNOME/librsvg/issues [gi]: https://wiki.gnome.org/Projects/GObjectIntrospection [contributing]: CONTRIBUTING.md [reporting-bugs]: CONTRIBUTING.md#reporting-bugs [d-d-l]: https://mail.gnome.org/mailman/listinfo/desktop-devel-list [federico]: https://people.gnome.org/~federico/ [platform]: https://developer.gnome.org/ [guadec-presentation]: https://people.gnome.org/~federico/blog/docs/fmq-porting-c-to-rust.pdf PKs1]8…fŒ(Œ(CONTRIBUTING.mdnu„[µü¤Contributing to librsvg ======================= Thank you for looking in this file! There are different ways of contributing to librsvg, and we appreciate all of them. * [Source repository](#source-code) * [Reporting bugs](#reporting-bugs) * [Feature requests](#feature-requests) * [Hacking on librsvg](#hacking-on-librsvg) There is a **code of conduct** for contributors to librsvg; please see the file [`code-of-conduct.md`][coc]. ## Source repository Librsvg's main source repository is at gitlab.gnome.org. You can view the web interface here: https://gitlab.gnome.org/GNOME/librsvg Development happens in the master branch. There are also branches for stable releases. Alternatively, you can use the mirror at Github: https://github.com/GNOME/librsvg Note that we don't do bug tracking in the Github mirror; see the next section. If you need to publish a branch, feel free to do it at any publically-accessible Git hosting service, although gitlab.gnome.org makes things easier for the maintainers of librsvg. To work on the source code, you may find the "[Hacking on librsvg](#hacking-on-librsvg)" section helpful. ## Reporting bugs Please report bugs at https://gitlab.gnome.org/GNOME/librsvg/issues If you want to report a rendering bug, or a missing SVG feature, please provide an example SVG file as an attachment to your bug report. It really helps if you can minimize the SVG to only the elements required to reproduce the bug or see the missing feature, but it is not absolutely required. **Please be careful** of publishing SVG images that you don't want other people to see, or images whose copyright does not allow redistribution; the bug tracker is a public resource and attachments are visible to everyone. You can also [browse the existing bugs][bugs-browse]. ## Feature requests Librsvg aims to be a small and relatively simple SVG rendering library. Currently we do not plan to support scripting, animation, or interactive features like mouse events on SVG elements. However, we *do* aim go provide good support for SVG's graphical features. Please see the "[reporting bugs](#reporting-bugs)" section for information about our bug tracking system; feature requests should be directed there. It is especially helpful if you file bug for a feature request along with a sample SVG file. ## Hacking on librsvg ### Working on the source Librvg uses an autotools setup, which is described in detail [in this blog post][blog]. If you need to **add a new source file**, you need to do it in the toplevel [`Makefile.am`][toplevel-makefile]. *Note that this is for both C and Rust sources*, since `make(1)` needs to know when a Rust file changed so it can call `cargo` as appropriate. 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. Please read the file [`ARCHITECTURE.md`][arch]; this describes the overall flow of the source code, so hopefully it will be easier for you to navigate. ### Taking advantage of Continuous Integration If you fork librsvg in `gitlab.gnome.org` and push commits to your forked version, the Continuous Integration machinery (CI) will run automatically. A little glossary: * ***Continuous Integration (CI)*** - A tireless robot that builds librsvg on every push, and runs various kinds of tests. * ***Pipeline*** - A set of ***jobs*** that may happen on every push. Every pipeline has ***stages*** of things that get run. You can [view recent pipelines](https://gitlab.gnome.org/GNOME/librsvg/pipelines) and examine their status. * ***Stages*** - Each stage runs some kind of test on librsvg, and depends on the previous stages succeeding. We have a *Test* stage that just builds librsvg as quickly as possible and runs its test suite. If that succeeds, then it will go to a *Lint* stage which runs `rustfmt` to ensure that the coding style remains consistent. Finally, there is a `Cross_distro` stage that tries to build/test librsvg on various operating systems and configurations. * ***Jobs*** - You can think of a job as "something that runs in a specific container image, and emits a success/failure result". For example, the `Test` stage runs a job in a fast Fedora container. The `Lint` stage runs `rustfmt` in a Rust-specific container that always contains a recent version of `rustfmt`. Distro-specific jobs run on container images for each distro we support. The default CI pipeline for people's branches is set up to build your branch and to run the test suite and lints. If any tests fail, the pipeline will fail and you can then examine the job's build artifacts. If the lint stage fails, you will have to reindent your code. ***Automating the code formatting:*** You may want to enable a [client-side git hook](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks) to run `rustfmt` before you can commit something; otherwise the `Lint` stage of CI pipelines will fail: 1. `cd librsvg` 1. `mv .git/hooks/pre-commit.sample .git/hooks/pre-commit` 1. Edit `.git/hooks/pre-commit` and put in one of the following commands: * If you want code reformatted automatically, no questions asked: `cargo fmt` ***Note:*** if this actually reformats your code while committing, you'll have to re-stage the new changes and `git commit --amend`. Be careful if you had unstaged changes that got reformatted! * If you want to examine errors if rustfmt doesn't like your indentation, but don't want it to make changes on its own: `cargo fmt --all -- --check` ***Installing rustfmt*** As of 2018/Jun, our continuous integration pipeline assumes the Rust nightly version of rustfmt. You can install it with ``` cargo +nightly install --force rustfmt-nightly ``` Note that rustfmt changes frequently. If the CI pipeline fails on the `Lint` stage because your code is formatted differently, try updating your rustfmt. Hopefully this will stabilize once rustfmt reaches version 1.0. ### Test suite Please make sure that the test suite passes with the changes in your branch. The easiest way to run all the tests is to go to librsvg's toplevel directory and run `make check`. This will run both the small unit tests and the black box tests in the `librsvg/tests` directory. If you need to add new tests (you should, for new features, or for things that we weren't testing!), or for additional information on how the test suite works, please see the file [`tests/README.md`][tests-readme]. In addition, the CI machinery will run librsvg's test suite automatically when you push some commits. You can tweak what happens during CI for your branch in the [`.gitlab-ci.yml` file](.gitlab-ci.yml) — for example, if you want to enable distro-specific tests to test things on a system that you don't have. ### Testing changes The most direct way to test a change is to have an example SVG file that exercises the code you want to test. Then you can rebuild librsvg, and run this: ``` cd /src/librsvg libtool --mode=execute ./rsvg-convert -o foo.png foo.svg ``` Then you can view the resulting `foo.png` image. Alternatively, you can use `./rsvg-view-3` for a quick-and-dirty SVG viewer. **Please update the test suite** with a suitable example file once you have things working (or before even writing code, if you like test-driven development), so we can avoid regressions later. The test suite is documented in [`tests/README.md`][tests-readme]. ### Creating a merge request You may create a forked version of librsvg in [GNOME's Gitlab instance][gitlab], or any other publically-accesible Git hosting service. You can register an account there, or log in with your account from other OAuth services. Note that the maintainers of librsvg only get notified about merge requests (or pull requests) if your fork is in [gitlab.gnome.org][gitlab]. For technical reasons, the maintainers of librsvg do not get automatically notified if you submit a pull request through the GNOME mirror in Github. [Please contact the maintainer][maintainer] directly if you have a pull request there or a branch that you would like to contribute. ### Formatting commit messages If a commit fixes a bug, please format its commit message like this: ``` (#123): Don't crash when foo is bar Explanation for why the crash happened, or anything that is not obvious from looking at the diff. https://gitlab.gnome.org/GNOME/librsvg/issues/123 ``` Note the `(#123)` in the first line. This is the line that shows up in single-line git logs, and having the bug number there makes it easier to write the release notes later — one does not have to read all the commit messages to find the ids of fixed bugs. Also, please paste the complete URL to the bug report somewhere in the commit message, so that it's easier to visit when reading the commit logs. Generally, commit messages should summarize *what* you did, and *why*. Think of someone doing `git blame` in the future when trying to figure out how some code works: they will want to see *why* a certain line of source code is there. The commit where that line was introduced should explain it. ### Testing performance-related changes You can use the [rsvg-bench] tool to benchmark librsvg. It lets you run a benchmarking program **on an already-installed librsvg library**. For example, you can ask rsvg-bench to render one or more SVGs hundreds of times in a row, so you can take accurate timings or run a sampling profiler and get enough samples. **Why is rsvg-bench not integrated in librsvg's sources?** Because rsvg-bench depends on the [rsvg-rs] Rust bindings, and these are shipped outside of librsvg. This requires you to first install librsvg, and then compile rsvg-bench. We aim to make this easier in the future. Of course all help is appreciated! [coc]: code-of-conduct.md [gitlab]: https://gitlab.gnome.org/GNOME/librsvg [bugs-browse]: https://gitlab.gnome.org/GNOME/librsvg/issues [maintainer]: README.md#maintainers [tests-readme]: tests/README.md [blog]: https://people.gnome.org/~federico/blog/librsvg-build-infrastructure.html [toplevel-makefile]: Makefile.am [tests-readme]: tests/README.md [rsvg-bench]: https://gitlab.gnome.org/federico/rsvg-bench [rsvg-rs]: https://github.com/selaux/rsvg-rs [arch]: ARCHITECTURE.md PKs1]ã^dÏ&& README.mdnu„[µü¤PKs1]8…fŒ(Œ(_CONTRIBUTING.mdnu„[µü¤PK˜*?