DUChain architecture changes, port away from SmartRange etc.

David Nolden zwabel at googlemail.com
Sat Jul 10 15:09:51 UTC 2010

My port is nearly finished, and the ported KDevelop is working again.
Some changes to kate are still missing to make it perfect, but
language authors can start looking at the code, and trying out now.

I didn't do a plain at simple "SmartRange -> MovingRange" conversion,
but I've done much more significant changes. Mainly, I've ripped out
all the editor dependencies in the core duchain stuff. The functions
that are left there are mainly convenience functions.

Now language-plugin authors won't have to care anymore about the
question whether the file is open in an editor, about
creating/updating smart-ranges, and all that complicated fragile stuff
that has cost me man-moths of work to make it somewhat run before the
4.0 release.

Here's how it works:
- The ranges within the TopDUContext for a file refer to one specific
file revision, which may be older than the current revision. Those
ranges/cursors are represented by KDevelop::CursorInRevision or
KDevelop::RangeInRevision objects.
- Ranges in the current document revision (for example the current
cursor in the editor) are generally represented by
KDevelop::SimpleRange and KDevelop::SimpleCursor.
- Convenience functions in KDevelop::DocumentChangeTracker,
KDevelop::DUChainBase, and KDevelop::RevisionReference allow you to
translate between revisions, thereby transforming a SimpleCursor to a
CursorInRevision or the opposite way.

- When updating the duchain, KDevelop::ParseJob cares about retrieving
the new document text, and translates all the ranges within the
TopDUContext from the old revision into the new revision (using the
foreground lock to access the document).
- When updating the duchain, you can simply match the existing ranges
in the duchain against the new ranges, as both are in the same
revision now.
- When parsing has finished, KDevelop::CodeHighlighting highlights the
code in the background, and then sends the highlighting-info to the
foreground, where the ranges are again translated to the current
revision, and then highlighted using KTextEditor::MovingRange.

Required changes to language plugins:
- You have to use the KDevelop::ParseJob functions readContents to get
the document contents, and translateDUChainToRevision before updating
the TopDUContext to translate its ranges to the new revision.
readContents now does more also the "read data from disk" part which
the language-plugins had to implement by themselves before. The
code-highlighting API works as before.
- Then you've got to replace SimpleRange / SimpleCursor with
RangeInRevision / CursorInRevision within all your parsing and duchain
handling code, this is a simple mass-replace (unfortunately we don't
have a plugin to do this yet).
- Remove all the Smart* code you had, and generally make the stuff
compile again (some APIs have changed due to removed SmartRange etc.,
but the port should be straightforward)
- The whole KDevelop::EditorIntegrator stuff doesn't exist anymore,
but you won't need it. :-)

Some of the abstract builders aren't required anymore, as they do
nothing significant, and make the code-structure much more
complicated. At least from the C++ support, I've removed
AbstractTypeBuilder and AbstractDeclarationBuilder from the builder
inheritance chain, which makes the parsing architecture simpler to
understand. However this is not required of course.

The branches can be found at:
git at gitorious.org:~zwabel/kdevelop/kdevplatform-zwabel.git
git at gitorious.org:~zwabel/kdevelop/kdevelop-zwabel.git

As I already said before, this should become the main development
line, and we should move it into a central place, so we can start
working on this code, and do a stable release based on it, at least
somewhat close to the KDE 4.5 release. IMO this should simply be the
trunk in our main development repository.

Greetings, David

More information about the KDevelop-devel mailing list