Inkscape Wiki - User contributions [en]

Working with SVN

2006-02-06T03:48:41Z

Inkblotter: /* How Do I Check Out a Working Copy? */

(This began a copy of [[WorkingWithCVS]]; bear with us as it is updated for SVN)

== Subversion (SVN) Basics ==

This node discusses the basics of using SVN.

For information on more advanced usage, see:

* [[WorkingWithSVNBranches]] - making branches and merging between them

=== Concepts ===

==== The Repository ====

SVN stores source code in a shared '''repository''' (in our case on Sourceforge's server). The repository contains all past and present versions of the code, and is shared by everyone.

==== Your Working Copy ====

To work with the source code, SVN requires you to '''check out''' a ''working copy''. This copy is private, so you can make and test any changes you like without disturbing anyone else.

If you have '''write access''' to the repository, when you are finished making your changes, you may '''commit''' your changes to the shared repository, making them available to everyone.

Alternately, you may generate a file containing the changes you made (a ''diff''), and send it to a developer with write access to be incorporated.

You can check out as many working copies as you want; they take up only your own disk space, and they are completely independent of each other.

If you no longer need a working copy, you may simply delete it.

=== Getting Started ===

==== Setting Up ====

==== How Do I Check Out a Working Copy? ====

To check out a copy of Inkscape from the SVN repository, you may use the following command:

svn checkout https://svn.sourceforge.net/svnroot/inkscape/inkscape/trunk inkscape

Here are what the options mean:

"checkout" ("co" means the same thing) specifies the action to take (check out a working copy).

"https://svn.sourceforge.net/svnroot/inkscape/inkscape/trunk" is a repository URL; in this case, it refers to the "main" development branch for Inkscape.

"inkscape" is the name of the directory to check out into

==== Now What? ====

You should have a complete working copy in the '''inkscape''' directory. You can cd to it and try compiling.

:Note: If it is a fresh checkout, you will need to run the ./autogen.sh shell script at the top level to create files needed to compile

When you're inside the working copy, you won't normally need to specify the repository URL, because SVN remembers where the working copy came from.

Note that a Subversion command only applies to the current directory and (possibly) any subdirectories. Normally (particularly for updates, diffs, and checkins), you will want to run the command from the top level of the project.

=== Bringing Your Working Copy Up-To-Date ===

Your working copy will not automatically include changes others have made to the repository since you checked it out.

To ''update'' your working copy, use this command:

svn update

=== Dealing with Conflicts ===

If you've made changes to your working copy, what happens if you update after someone has commited changes to the same files?

Normally, SVN can work this out on its own. Sometimes you have to help it along, though. If SVN says there were conflicts, look for which files have a ''C'' next to them in its progress output. Some of those may have unresolved conflicts. You can also search for '=======' in the files themselves to find any unresolved conflicts.

<<<<<<< ''filename''
The changes in your version will be here
=======
The changes the other person will be here
>>>>>>> ''some version here''

Sometimes you will keep one set of changes and discard the other, and sometimes you will combine the two. It will require a judgement call on your part either way. Talk to the person who made the other set of changes or ask on the mailing list if it's unclear what's going on. Remember that SVN is no substitute for communication.

Also, always make sure to build and test after an update to make sure that the combined changes work as intended!

=== Generating a Diff ===

('''Always''' update before generating a diff!)

From the top-level directory, run the command:

svn diff -x -u3 > filename

-x -u3 specifies which format to use (a unified diff with three lines of context). This is the recommended diff format.

This will create a file describing the changes you have made, though if you have created new files as part of your changes, you will need to include those separately too when emailing them to the list or another developer for inclusion.

=== Automatic Commit Diff ===

[ fixme: how to do this in SVN? ]

To always generate a diff when you commit to CVS, set the environment variable "CVSEDITOR" to the following script:

#!/bin/bash
# get rid of redhat 9 locale ugliness
unset [[LC_CTYPE]]
# Turn on ro access (to stop multiple locks) for local roots
grep @ CVS[[/Root]] >/dev/null 2>&1 || export CVSREADONLYFS=1
# Tell the user what's going on
echo Building diff...
cvs diff -up 2>/dev/null | perl -ne 'print "CVS: $_" unless /^\?/' >> "$1"
exec ${EDITOR:-vi} "$1"

If the above script is named "~/bin/cvsdiffvi", then assuming you run the bash shell, you can add the following your .bashrc file:

export CVSEDITOR=~/bin/cvsdiffvi

Now, every time you commit, the entire diff will be visible to you as you write your commit comments.

=== Applying a Diff ===

A diff file can be applied to the codebase using the 'patch' command.

If the diff was made as <code>inkscape/src/thingy.cpp</code> and you're in the "inkscape" directory, you'll want to use the command:

patch -p1 < thingy.diff

Depending on how many path elements are part of the diff, you'll need to strip them with -p1, -p2, etc.

=== Committing your Changes ===

('''Always''' update before committing!)

If you have write access to the repository, you can commit your changes like this:

Before you commit, please make sure that you describe the changes you have made in the [[ChangeLog]] file at the top-level directory.

svn commit -m "Your description of your changes goes here"

Tip: even if you are committing directly, you still might want to generate a diff. It's a good reference to look at when you're filling out the [[ChangeLog]], since it will remind you of all the changes you've made.

=== Adding Files to the Repository ===

To add new files as part of your commit, you will need to run:

svn add ''files and directories to add go here''

Before you commit. This also goes for new directories.

The actual addition or removal will not take effect until you commit.

=== Removing Files from the Repository ===

svn remove ''files to remove go here''

Inkscape glossary

2006-01-24T15:14:08Z

Inkblotter: despam

WorkingWithSVNBranches

2006-01-23T04:19:25Z

Inkblotter:

(This began as a copy of [[WorkingWithCVSBranches]]; bear with us as we update it to reflect SVN)

===== Starting Work on an Existing Branch =====

* checking out a specific branch of MODULE into DIR

svn checkout https://svn.sourceforge.net/svnroot/inkscape/MODULE/branches/BRANCH DIR

===== Making Your Own Branch =====

:1. Make a branch based on the revisions in your working copy (commit before you do this!)

cvs -z3 tag -b BRANCH

:2. Switch your working copy to that BRANCH (as shown earlier)

cvs -z3 update -PAd -r BRANCH

:3. Tag the initial revisions in your branch (you'll need this for merging easily)

cvs -z3 tag [[BRANCH_START]]

===== Merging Your Changes =====

:1. Commit your work and resolve any conflicts

:2. Tag the revisions for this merge

cvs -z3 tag [[BRANCH_MERGE]]

:3. Switch your working copy back to the branch you want to merge to (HEAD is the default if you don't specify a branch with -j)

cvs -z3 update -PAd -r [[OTHER_BRANCH]]

:4. Merge the changes between [[BRANCH_START]] and [[BRANCH_MERGE]] into your working copy

cvs -z3 update -Pd -j [[BRANCH_START]] -j [[BRANCH_MERGE]]

:5. Check for any conflicts and commit the changes

If you want to work on BRANCH some more, you'll need to switch your working copy back to BRANCH again.

For future merges, you'll need to tag the revisions for those merges with unique tags (e.g. [[BRANCH_MERGE_2]], [[BRANCH_MERGE_3]], etc...), and only merge the changes between the previous merge and the new one.

This is so you don't end up merging the same set of changes twice.
Example:

First merge: -j [[BRANCH_START]] -j [[BRANCH_MERGE]]
Second merge: -j [[BRANCH_MERGE]] -j [[BRANCH_MERGE_2]]
Third merge: -j [[BRANCH_MERGE_2]] -j [[BRANCH_MERGE_3]]

If you merge to another branch that you've never merged to before, you'll need to merge from [[BRANCH_START]] up through [[BRANCH_MERGE_3]] to catch up.

Working with SVN

2006-01-23T04:18:33Z

Inkblotter:

(This began a copy of [[WorkingWithCVS]]; bear with us as it is updated for SVN)

== Subversion (SVN) Basics ==

This node discusses the basics of using SVN.

For information on more advanced usage, see:

* [[WorkingWithSVNBranches]] - making branches and merging between them

=== Concepts ===

==== The Repository ====

SVN stores source code in a shared '''repository''' (in our case on Sourceforge's server). The repository contains all past and present versions of the code, and is shared by everyone.

==== Your Working Copy ====

To work with the source code, SVN requires you to '''check out''' a ''working copy''. This copy is private, so you can make and test any changes you like without disturbing anyone else.

If you have '''write access''' to the repository, when you are finished making your changes, you may '''commit''' your changes to the shared repository, making them available to everyone.

Alternately, you may generate a file containing the changes you made (a ''diff''), and send it to a developer with write access to be incorporated.

You can check out as many working copies as you want; they take up only your own disk space, and they are completely independent of each other.

If you no longer need a working copy, you may simply delete it.

=== Getting Started ===

==== Setting Up ====

==== How Do I Check Out a Working Copy? ====

To check out a copy of Inkscape from the developer CVS, you may use the following command:

svn checkout https://svn.sourceforge.net/svnroot/inkscape/inkscape/trunk inkscape

Here are what the options mean:

"checkout" ("co" means the same thing) specifies the action to take (check out a working copy).

"https://svn.sourceforge.net/svnroot/inkscape/inkscape/trunk" is a repository URL; in this case, it refers to the "main" development branch for Inkscape.

"inkscape" is the name of the directory to check out into

==== Now What? ====

You should have a complete working copy in the '''inkscape''' directory. You can cd to it and try compiling.

:Note: If it is a fresh checkout, you will need to run the ./autogen.sh shell script at the top level to create files needed to compile

When you're inside the working copy, you won't normally need to specify the repository URL, because SVN remembers where the working copy came from.

Note that a Subversion command only applies to the current directory and (possibly) any subdirectories. Normally (particularly for updates, diffs, and checkins), you will want to run the command from the top level of the project.

=== Bringing Your Working Copy Up-To-Date ===

Your working copy will not automatically include changes others have made to the repository since you checked it out.

To ''update'' your working copy, use this command:

svn update

=== Dealing with Conflicts ===

If you've made changes to your working copy, what happens if you update after someone has commited changes to the same files?

Normally, SVN can work this out on its own. Sometimes you have to help it along, though. If SVN says there were conflicts, look for which files have a ''C'' next to them in its progress output. Some of those may have unresolved conflicts. You can also search for '=======' in the files themselves to find any unresolved conflicts.

<<<<<<< ''filename''
The changes in your version will be here
=======
The changes the other person will be here
>>>>>>> ''some version here''

Sometimes you will keep one set of changes and discard the other, and sometimes you will combine the two. It will require a judgement call on your part either way. Talk to the person who made the other set of changes or ask on the mailing list if it's unclear what's going on. Remember that SVN is no substitute for communication.

Also, always make sure to build and test after an update to make sure that the combined changes work as intended!

=== Generating a Diff ===

('''Always''' update before generating a diff!)

From the top-level directory, run the command:

svn diff -x -u3 > filename

-x -u3 specifies which format to use (a unified diff with three lines of context). This is the recommended diff format.

This will create a file describing the changes you have made, though if you have created new files as part of your changes, you will need to include those separately too when emailing them to the list or another developer for inclusion.

=== Automatic Commit Diff ===

[ fixme: how to do this in SVN? ]

To always generate a diff when you commit to CVS, set the environment variable "CVSEDITOR" to the following script:

#!/bin/bash
# get rid of redhat 9 locale ugliness
unset [[LC_CTYPE]]
# Turn on ro access (to stop multiple locks) for local roots
grep @ CVS[[/Root]] >/dev/null 2>&1 || export CVSREADONLYFS=1
# Tell the user what's going on
echo Building diff...
cvs diff -up 2>/dev/null | perl -ne 'print "CVS: $_" unless /^\?/' >> "$1"
exec ${EDITOR:-vi} "$1"

If the above script is named "~/bin/cvsdiffvi", then assuming you run the bash shell, you can add the following your .bashrc file:

export CVSEDITOR=~/bin/cvsdiffvi

Now, every time you commit, the entire diff will be visible to you as you write your commit comments.

=== Applying a Diff ===

A diff file can be applied to the codebase using the 'patch' command.

If the diff was made as <code>inkscape/src/thingy.cpp</code> and you're in the "inkscape" directory, you'll want to use the command:

patch -p1 < thingy.diff

Depending on how many path elements are part of the diff, you'll need to strip them with -p1, -p2, etc.

=== Committing your Changes ===

('''Always''' update before committing!)

If you have write access to the repository, you can commit your changes like this:

Before you commit, please make sure that you describe the changes you have made in the [[ChangeLog]] file at the top-level directory.

svn commit -m "Your description of your changes goes here"

Tip: even if you are committing directly, you still might want to generate a diff. It's a good reference to look at when you're filling out the [[ChangeLog]], since it will remind you of all the changes you've made.

=== Adding Files to the Repository ===

To add new files as part of your commit, you will need to run:

svn add ''files and directories to add go here''

Before you commit. This also goes for new directories.

The actual addition or removal will not take effect until you commit.

=== Removing Files from the Repository ===

svn remove ''files to remove go here''

GtkMMification

2005-09-03T14:22:20Z

Inkblotter: *

Gtk+ and GtkMM interact cleanly. This task is to replace individual widgets and dialogs with their GtkMM ports so as to reduce the code size and make code reading easier.

We won't be using libglade [1], but we may consider other GtkMM-based derived widgetsets, such as the ones used for the new [[The_Gimp]] interface.
There are several reasons for not using libglade. First, it imposes an extra dependency that has proven problematic in the past. Second, while it allows for layout of custom widgets, it isn't really designed for that purpose; Inkscape will have its fair share of custom widgets. Third, it is not felt to be suitable to dynamically laid-out dialogs; we wish to make the new dialogs be responsive to changes in the Action system, so will wish to make the dialogs very dynamic. Fourth, we will need to be able to specify UI changes triggered by user actions, which glade does not provide.

That said, use of Glade is encouraged for prototyping and for module/extension interfaces. But for core UI, any Glade-generated code will need to be coded up properly using clean Gtkmm. You'll probably find, though, that Gtkmm's packing toolkit makes visual form layout editing unnecessary.

[1] Comment from Murray Cumming: I can not emphasis enough the great benefits of using libglade(mm). I use it even for layouts that use custom widgets, using get_widget_derived(). Even if you aren't sure about that, I'm sure that you have lots of completely static dialog boxes for which you could obviously use libglade. Using libglade leads to better UI. Murray.

: Thanks, yes it does seem quite nice, yet the rationale above still seems to hold. Glade seems helpful for laying out simple static dialogs, however those are also fairly straightforward to code by hand. The extra dependencies, plus the complexity of code partly written by hand and partly generated, plus the level of dynamicism needed still suggest that we'll get less out of glade than the cost of inclusion.

== Theming ==
As part of doing the migration to gtkmm you should try and get icon theming working properly. While not directly related to the port I think fixing it when redoing the GUI anyway is a good time. There are a couple of things to keep in mind. For icon shared by Inkscape with all GTK+ and GNOME apps (file new, file open) etc. you should just use the standard icons. Look at gedit for sample code of how it is done. For icons that Inkscape shares with other drawing apps like [[The_Gimp]] you should adopt the stock icons defined by [[The_Gimp]] (floodfill is a good example here).

For the remaining icons you would need to define them yourself, good thing here would be to make sure Sodipodi could use the same stock icons definitions so that when someone icon themes Sodipodi or Inkscape both apps picks up the correct icons.
-- Uraeus

== Implementation ==

Do not include the generic <gtkmm.h> header, as that includes all gtkmm headers (about a megabyte or so).
Instead include the specific headers needed.

[ n.b. if pch is used, including all the gtkmm headers would not impact things so badly. ]

An easy first-step in converting existing code to Gtkmm would be to replace existing character strings with
Glib::ustring, which has a similar interface to std::string but supports UTF-8. Watch out for pointer arithmetic
or functions like strlen().

We will need to create a menubar from Gtk::MenuBar. Ideally, this should be dynamically built based on
registered verbs (Actions) in the system, as modified by appropriate user preferences.

The XML Editor will require refactoring to make use of the TreeView widget. A few other proposed dialogs have been conceived to "be like the xml editor, except..." so it would probably be wise to create a general purpose TreeEditor class that these dialogs could inherit from, and that provides the general functionality of handling trees and editing their contents.

Change the text properties editor to use TextView. Can we get more powerful text editing than is normally
available? E.g., search-and-replace, spellcheck, etc.

The right-click Popup Menu needs to be redeveloped to also tie into the Action system, such that the
contents of this menu change dynamically based on what the mouse is hovering over - for text, it should
provide text-modification actions, whereas over a node in a path it should show node-editing capabilities.

Toolbars will need to be built from the Action tree, as modified by the user preference settings.
There are four principle toolbars: The master, auxillary, extension, and custom toolbars. By default
these are positioned on the left, top, bottom, and right sides of the canvas, respectively. The master
toolbar is a set of radio buttons corresponding to different aux toolbars; changing the selected radio button
changes which aux toolbar is shown. The extension toolbar is used to show third-party tools. The
custom toolbar is left to be defined by the user.

Inkscape will require an easy way to get to a variety of dialog pages for setting properties, selecting
options, etc. etc. In release 0.35 this was handled via a plethora of popup dialogs, however this is not
felt to be an adequate solution. In the new [[The_Gimp]] 2.0 look and feel, access to properties are through a
combined dialog, where each page of the dialog is accessed via tabbed pages. This is what is being discussed and planned on PreferencesDialog. Other approaches should
be researched and evaluated.

The standard Gtk font and color dialogs won't be suited to our needs; we'll need to fold in similar capabilities
into the combined dialog mentioned above.

Drag and Drop will need further investigation. Widgets can be specified as sources or destinations for
drag and drop actions. It should be possible to drag text from the canvas, other widgets, or external
sources into any text entry areas. Dragging of SVG objects off of the canvas into a style editing widget
or panel should cause it to adopt the style settings of the dragged object.

Every widget should have a unique, patternized name and take signals in order to operate it. This is to allow
scripting such as for automated testing purposes. It should be possible to programmatically drive Inkscape
through invoking signals externally, which should result in testable transforms of the document. We can
keep a library of these invocation scripts and use them for regression testing.

Dialog windows that aren't shown at startup should be built-up after program initialization during idle times
or timeout events. Action button images that are not shown initially should also be rendered for display
during idle times, after the program has initiated. The goal is to get the app to the point that it can accept
editing commands as rapidly as possible by putting off program initialization work.

We'll need to create a set of our own signals. This can replace situations where pointers are being
passed around from object to object. Normal SigC::Signals objects can be used for this.

=== Internationalization ===

This will muchly work in the same manner as it has in the codebase, using the english versions of text in
gettext() function calls via the _() macro. The xgettext script extracts the strings into the inkscape.pot
file. Translators copy this file to languagename.po and edit to suit. The msmerge script updates the .po
files from the regenerated .pot file.

Info on getting the gnome-i18n project to help with translations can be found here:
http://www.gtkmm.org/gtkmm2/docs/tutorial/html/ch20s04.html

=== GObject vs. NRObject vs. C++ ===

With GObject, classes are represented by integer ids which are allocated when classes are registered. The usual pattern is to provide some accessor function (normally class_name_here_get_type()) to get a class id for a particular class, which checks if the class has been registered yet, and if not it does so.
The registration function itself allocates sufficient memory for the class structure, then copies a populated class structure from the superclass over it (thereby filling in the fields that are common with the superclass).
At that point it calls the class init function which takes care of overriding any superclass functions, and populating any new ones that aren't provided by the superclass.

Now, in terms of creating a new object instance, that generally happens via a call to g_object_new(), which takes a type identifier that allocates enough memory for the given type, then walks down the inheritance chain calling init functions in succession. The init functions are responsible for initializing any members.

Now, there are a couple important points to note:
# GObject zero-fills object memory before starting the initialization process
# As part of initialization, it fills in a couple fields in the GObject header; mainly a pointer to an instance of the appropriate class object (which acts as a vtable, among other things)
# the presence of virtual functions in derived classes won't alter the layout (since there's already a vtable pointer in NRObject), but multiple inheritance will still break the expectations of the GObject-style casting macros.

Generally it's safest to stick with single inheritance below NRObject.

The first item in the SPView structure is a 'GObject object'; this is really intended to be an 'is-a' relationship. I.e., object is really the parent object that SPView is "derived" from. For clarity, this should be rewritten to be:

class SPView : public GObject {
public:
...
};

Next, SPView should be converted to use NRObject in place of GObject, as a transitional step towards full C++/Gtkmm. In doing this, all the SPView-related GObject macros and functions will need to be converted to their NRObject equivalents. But before you can do that, all of the SPView signals need to be converted to sigc++ signals. These signals have constructors that need to be called, so those constructors will need to be called manually from the init function, using placement new notation.

In the most generic sense, "Placement new" refers to the notation used to pass additional arguments to the new operator, but in its classic usage it's used to pass a single void*, which is used as the address of memory to initialize for the given object type, rather than allocating new memory itself. In essense, `new (ptr) Blah();` means to run Blah's constructor on the memory pointed to by ptr.

Also, the destructor will need to be manually called. This is done via the notation `ptr->~Blah();` In the case of a template class (like signals), you leave off the signal parameters. This needs to be done (as members) for each signal in the init()/dispose() functions for a GObject class with signals. Once you convert to NRObject, you'll need to get rid of those, as the initialization will be done automatically at that point.

Before converting to NRObject, it's imperative to start explicitly initializing every member. GObject allows skipping initialization since it automatically zero-fills the structure, but pure C++ will not. NRObject deliberately initializes with garbage to make sure you don't forget. ;-)

Finally, SPView should be converted fully into C++. This can be done in several steps. The class should be renamed from SPView to just View, put into the Inkscape::UI::View namespace, and moved into the src/ui/view/ directory. This will require changing all code referring to SPView, obviously. Referrers should be changed to use the member function style instead of macros or procedural style calls.