Developer manual
Inkscape Developer’s Manual
Please first read the short introduction:
Getting started with development ---> https://inkscape.org/develop/getting-started/
Introduction
For those of you just joining us, or who have been with us but are just now getting the itch to work on Inkscape, I thought I’d give some tips for how to get started working in the codebase based on our own experiences.
One of the first things most people wonder is “What should I work on?”. As you may have already noticed, we generally don’t “assign” projects. We figure there’s plenty more work to do than people to do it, so you may as well work on something that you’re either interested in or that adds something of benefit to you; that’s extra motivation to get your own itches scratched.
If you’re really stumped though, we keep a detailed Roadmap in wiki that you’re welcome to browse through to look for ideas of things to work on. Tasks that do not have names beside them are open for anyone to take; if you want to take ownership of a task, just put your name beside it. Feel free to add or reword tasks as needed, although try not to load up the current milestone with tasks that aren’t critical for the release. Feel free to work on stuff that is several milestones down the road; there’s rarely any problem with getting stuff done sooner than planned. ;-)
We have a process for gaining GitLab Developer access. The reason is that while it is important that we keep access to the codebase open, we don’t want to be crazy and leave it wide open to any random passer-by. The process is that we require that the person make two contributions (patches, documentation, web collateral, etc.) and then make a request to get account access.
In general you won’t need Developer role in order to start doing development, because you can create merge requests with only a regular account. Due to GitLab constraints however, you won't be able to run Windows or MacOS CI - but we can always do that for you.
When you first start hacking on Inkscape code, I wouldn’t recommend taking an objective of implementing a specific feature, because you will need some time to familiarize yourself with the codebase, and because you won’t really know what features are going to be straightforward to implement and which will be highly challenging. Of course, if you have the time and love adventures, this might be a fun way to go.
There are four approaches that I’ve seen people effectively use in getting into the codebase:
- Write code documentation. Some people who don’t mind adding comments to code or writing docs find it useful to just go through code they’re interested in working on and writing up what it does. The codebase is in dire need of better docs, so this approach pays dividends well into the future.
- Fix bugs. Tracing down the cause of reported bugs is an effective way to gain understanding of the codebase in small chunks. Many common bugs can be traced down and fixed in a matter of hours, and often will identify some bit of code in need of refactoring or extension. Note that some of our older bugs are in the system because they’re hard to fix, so you’ll want to work on the more recent ones.
- Chip in on a group effort. Occasionally we identify a major refactoring effort (such as when we converted from C to C++), that we encourage lots of people to help on, in the philosophy that many hands make light work. This work tends to be pretty rote so is not hard for new folks to get involved with; it just takes time. We generally have one of these kinds of efforts per release. It usually isn’t glamorous work, but in aggregate moves the codebase forward in a major way.
- Subsystem/module work. Some people want to get their hands in the
details quick, so take the approach of developing new code separate
from the codebase, to be integrated in later. This generally tends
to take a larger time commitment than the other approaches, but can be
an effective approach in some circumstances. We have a SVN module
called
experimentalthat you’re welcome to house your work until it’s ready for prime time.
Beyond that, you’re going to find the documentation for the Inkscape code is pretty scarce. We’ve worked on bits and pieces but unfortunately the vast majority of the code is undocumented. On the plus side, often you can implement the stuff you care about after learning only a limited portion of the codebase.
I think you’d find Inkscape an enjoyable Open Source project to work on. There’s a huge range of interesting and useful skills that can be learned from it, plus the developers are great guys to participate with. The project itself runs smoothly and puts a premium on keeping things friendly and low-stress, so heated arguments are rare. The users have been great to work with and very appreciative of even small new features and fixes. Plus, since Inkscape is so visual in nature, it’s very cool to see how your little changes make noticeable improvements to the app overall.
C++ Reference
- The C++ Core Guidelines. A set of rules for using modern C++ well, emphasizing safety and simplicity.
https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines
- The C++ FAQ (with answers). We strongly recommend that everyone read this site comprehensively. You should not need to bookmark it, it should already be at the top of your autocomplete list!
https://isocpp.org/wiki/faq
http://www.parashift.com/c++-faq-lite (previous version)It is actually more in-depth than the name FAQ suggests. Many experienced C++ programmers would benefit from it.
- C++ Reference. Documentation of all features of the language and standard library.
Please use const
Please be very aggressive in adding const to any code you write. It will help us understand code better and will prevent bugs from creeping in. It is very easy to remove const later on, but very hard to add it.
const can go on either side of a type. However once you get into references and pointers and such with C++, you generally read those from right-to-left. So it makes the code a little more legible if the const comes between the variable type and name.
int const foo; // RTL reading gives "foo is a constant int".
And then:
int const & foo; // RTL reading gives "foo is a reference to a constant int"
int const * foo; // RTL reading gives "foo is a pointer to a constant int"
whereas:
int * const foo; // RTL reading gives "foo is a constant pointer to an int"
Read also:
Strings
Please make sure any user-visible strings are localizable. This requires wrapping them with "_(" and ")", like so:
"Select object"
becomes
_("Select object")
In case the interpretation of the string may be ambiguous or may differ according to context, you can add a context prefix (that won't be displayed) in order to eliminate the ambiguity.
"Ambiguous string"
can then become
C_("Context", "Ambiguous string")
For more complex things, please check the gettext/localization documentation. See also http://library.gnome.org/devel/glib/unstable/glib-I18N.html
Implementing User Interface Changes
UI improvements are enjoyable to work on because they produce visible changes in how Inkscape works. These improvements are one of the most tangible ways to help improve how Inkscape works; thus, we strongly support new developers wishing to work in these areas.
It is also very important to us that Inkscape presents an organized, productive, and easily discoverable interface to users. Because of this it is important that new Inkscape UI developers work to ensure changes make Inkscape’s UI *more* consistent, *more* flexible, *more* cohesive, and so on. We don’t have firm rules about what can and cannot done, in order to ensure plenty of freedom for innovation. However, we can outline some general principles and guidelines that are important to keep in mind:
Don’t please the artist—BE the artist. Many times UI is designed and created by programmers who “understand what the user wants”. But in Inkscape we believe that the best requirements list is the list inside the user’s head. Requirements docs, usability studies, and so on are very indirect ways of transferring this gut-level understanding from user to programmer. We believe the best way to ensure this information is communicated clearly is for the user to BE the programmer. Or, alternatively, for the programmer to BECOME a user.
This is why we so strongly encourage users to get involved in coding, and why we so strongly encourage programmers to focus on the features that are most important to them personally. This is also why it is absolutely critical to pay close attention to what users report when using a new feature—often they can tip you off to alternate designs that achieve the same result in a better way.
Eliminate limitations. Commercial software is often developed to fulfill feature requirement lists from a marketing department. As such, it’s common to see the feature implemented to meet the requirement exactly, and no more. However, especially with artistic software, art is often found outside what seems reasonable. So when putting in a new feature, avoid the temptation to limit it to what you expect people to use it for—instead generalize it and open as many parameters as possible for tweaking, and let the artist decide what is reasonable. That’s their job.
As an example, a drawing program might want to support the features “feather” and “drop shadow”. Obviously, users need these important features. Commercial software may well implement these as distinct features, each with their own UI controls. However, these features are just special cases of the more general gaussian blur, and in Inkscape we implemented *that*. With that in place, artists can do feathering and blur, and a variety of other effects.
It is interesting to note that, as an open collaborative standard, SVG necessarily has the same goals as Inkscape: a minimum set of universal, well thought-out building blocks that can accommodate the widest possible range of graphics and applications. Thus, simply by following the SVG philosophy, Inkscape scores quite a few important points over commercial software. Live clones, patterns that can be contain any objects, layers that are essentially groups and can be easily converted to/from groups. These are all examples where the underlying universality of SVG directly translates into extremely valuable user features.
Implementing New SVG Features
The most important way to help Inkscape is to implement a new SVG feature in it. Our hope is to eventually support ALL SVG features, so if you can help check one off the list, it brings us close to the nirvana of 100% SVG compliance. :-)
Generally we find that implementation of an SVG feature goes through three discrete stages:
- Find the appropriate tags and attributes in the SVG spec
- Implement support for rendering files with these tags
- Implement support for UI controls to edit the tags
Step 1 is mostly a research project. Start by reading the SVG spec so you can learn about the tag, the attributes that go with it, and so forth. It is good practice to set up a page in the Wiki for storing your notes as you do this process, so that in case you don’t make it to steps 2 and 3, then maybe someone else can benefit from your research.
Step 2 is the fun part. It helps to be comfortable with Inkscape internals for this part. Depending on the feature, it may require advanced knowledge of transformation, rendering, document management, and so on. For this part, just hand-edit an SVG file to put the tags in that you found in step #1, and keep plugging away at the code until Inkscape displays things as the specification dictates. It can help to compare your work with Batik, as we use that program as our reference implementation.
Step 3 is the most important stage. It is the point at which the feature becomes available for users. This step often requires knowledge of Gtk+, for creating dialogs, widgets, menus, etc. for allowing the user to edit the characteristics of the feature. Be sure to listen to feedback from other developers and users—especially if there are different opinions. It is hard to come up with UI that everyone can agree on, but it is worth the work to achieve this—the more critique your UI survives, the better loved the feature will be for future users.
Looking through Inkscape’s history, these stages are often done by different people. If you’re new to Inkscape, you may find working on stages 1 and 3 easiest, but there are many developers who can answer questions when you’re ready to dig into the internals, so don’t be afraid to ask questions!
Standards Compliance - Extension Namespaces
- Only elements and attributes from our extension namespaces that do not affect rendering may be saved in SVG documents.
- Generally, this means that extension elements and attributes should only be used to provide UI hints.
- Extension elements and attributes should only be used where an existing facility provided by XML or SVG is not sufficient.
Directory Organization
Distribution / Packaging Files
Files related to generation of distribution packages should go under /packaging.
A variety of items are installed in addition to the program itself, and placed into a share directory structured as follows:
AUTHORS
NEWS
clipart/
examples/
extensions/
fonts/
gradients/
icons/
keyboards/
markers/
palettes/
patterns/
screens/
about.svg
templates/
tutorials/
In the codebase, all of these are placed in inkscape/share/. The idea is that in theory, this entire tree structure can be copied into place on the user’s machine.