New Approach to Documentation

15. May, 2011

Documentation usually has these three attributes: It’s incomplete, outdated and plain wrong.

That doesn’t apply to every bit of information in your documentation but it you can be sure the statement above is correct for the whole documentation.

As a consumer of such documents, it’s a nice puzzler to determine into which of the three categories a bit of information belongs.

This leads to the common “we hate documentation” stance that all software developers soon adopt, no matter if they have to write/maintain the documentation or if they have to use it.

As we all know, the only reliable source of documentation are unit tests. But they can still be incomplete (= missing the example you need) or outdated (= missing examples for the latest API).

The solution? Generate documentation from the source code. And I don’t mean “from javadoc in the source code”, I mean literally from the code. If a method is used in a certain way in 317 places in your code and once in a different way, then you have two examples. One of them probably works, the other is probably documents a bug which your tests missed.

Eclipse is starting to get support for this. The first step was code completion. Now we have a couple of guys working on Eclipse Code Recommenders.

This summer, Stefan Henß starts to work on an “extended documentation platform” for Eclipse.

Leave a Comment » | Software | Tagged: , , , , | Permalink
Posted by digulla

RC1 of Testing Ready For Testing [Updated]

15. May, 2011

I’ve recreated the testing repository using the latest version of my Maven Tools 4 Eclipse.

To browse the repository, please use the Nexus interface.

If you pull in any dependencies from the repository, non-Eclipse artifacts will come from from Project Orbit. If you want non-Eclipse dependencies (like log4j) from Maven Central, you need to change your profiles.

Deactivate “m4e.orbit” and activate “m4e.maven-central“. From the command line, that’s “-P m4e.maven-central” but I suggest to put these into your settings.xml (add “<activeProfile>m4e.maven-central</activeProfile>” to it).

Note that you don’t need to deactivate the profile m4e.orbit. As soon as you specify a profile on the command line or via the settings, it’s deactivated automatically.

“mvn help:active-profiles” and “mvn dependency:tree” are your friends.

Let me know if you find anything missing, odd, broken by  filing a bug or posting a comment here.

UPDATE 2011-05-30

Some dependencies from the new repo can also be found on Maven Central. One nasty problem is that both repos contain org.eclipse.equinox.app but the version from Maven Central contains odd dependencies which break your build.

To fix this, add this to your parent/root POM:

  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>org.eclipse.dash</groupId>
        <artifactId>dependency-management</artifactId>
        <version>3.6.2</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    <dependencies>
  <dependencyManagement>

This will limit all version ranges to the versions found in our new repository. Since Maven Central didn’t import new versions for at least one year, this should fix all problems.

Related posts:

Leave a Comment » | Software | Tagged: , , , , , | Permalink
Posted by digulla

Maven Tools for Eclipse: M2 Repository Analysis And Dependency Management

13. May, 2011

I’ve finished RC1 of my set of tools to import Eclipse plug-ins into Maven 2 repositories. You can find the source on github. It needs Python 2.7 and lxml. pip is your friend.

The new features: There is now a tool to analyze the M2 repository for oddities. Currently, it can find these issues:

  • Dependencies which are used but not part of the repository
  • Dependencies which are used with different versions or version ranges (i.e. when one POM includes a dependency with 1.0 and another POM pulls in the very same dependency with version 1.1)
  • Dependencies which are used without versions or version ranges or a catch-all version like [0,)
  • Several versions of the same artifact in the repository

Plus it prints a list of all POMs in the repo with files (jar, pom, sources, test-sources, …). Here is a sample report.

The last tool can create a POM file with a dependencyManagement element containing the versions of the POMs in the repository. You can use this to nail down all versions to the ones existing in your repository (so you don’t accidentally pull in something you don’t want).

Lastly, I’ve enhanced the patch tool. Instead of overwriting replaced dependencies, it will now move them into a new profile. This way, users of the repository can specify which dependency they want (the one from the repository or, say, one from Maven Central).

I will try to build a new testing repo over the weekend so we can start wrapping up the necessary patches for a release.

Related posts: Eclipse 3.6.2 Artifacts for Maven 2

2 Comments | Software | Tagged: , , , , , | Permalink
Posted by digulla

Mysterious Eclipse Hangs

15. April, 2011

If your Eclipse installation hangs, there can be several reasons. If it happens while your tests run, chances are that a test printed an exception to the console view. If the exception is very wide, this can cause Eclipse to hang for a few seconds: Bug 175888 – ConsolePatternMatcher causes large delays with some large input.

I’m working on a fix.

1 Comment | Software | Tagged: , , , | Permalink
Posted by digulla

Windows 7 Libraries Trigger Eclipse Builds

15. April, 2011

If you’re on Windows 7, you may know this odd behavior: For some reason, Eclipse goes into a build frenzy. Every few seconds, it will rebuild the workspace.

The reason: You added your workspace to a Windows 7 Library and you have “Refresh Automatically” enabled.

My guess is that indexing of Windows 7 Libraries creates temporary files which make Eclipse believe something changed in the Workspace. Which causes a rebuild. Which makes Windows re-index the workspace.

Workaround: Remove your workspace from the library or disable “Refresh Automatically”.

See also: Bug 342931 – Windows 7 Libraries trigger rebuilds

Leave a Comment » | Software | Tagged: , , , , , | Permalink
Posted by digulla

Maven Tools for Eclipse: Patching POMs

11. April, 2011

I’ve added a new feature to my Maven tools for Eclipse: Applying patches to POMs.

This is a first step towards solving issues like this one: Bug 342046 – Invalid third party dependencies in Mavenized BIRT plugins

I’m not 100% happy with the result, though. Currently, the patch overwrites the original code. I think it would be much better if it created a profile instead. This way, you could see the original code and it would be simple to switch between different solutions for a problem in a POM.

The two standard problems are:

  • Bad version (no version, version range or wrong version)
  • Dependency name

The latter is introduced by the fact that Eclipse projects need to pull dependencies via Project Orbit. Orbit often renames dependencies so there is a naming conflict if you pull your dependencies from Maven Central. So we need a way to say “I’m using Orbit” and “I want Maven Central”.

1 Comment | Software | Tagged: , , , , , | Permalink
Posted by digulla

Eclipse 3.6.2 Artifacts for Maven 2

20. March, 2011
Apache Maven logo.

Image via Wikipedia

Update: The project has its own web site, now.

Two days ago, I told you about Project Dash and my new tools for it. Well, we did run them over the weekend and import a lot of stuff from Eclipse 3.6.2 into a brand new testing Maven 2 repository.

So if you want to use Eclipse bundles in Maven 2 for your own projects (SWT, EMF, even BIRT), have a look and let me know:

  • Did I miss anything?
  • Is anything wrong? Version numbers, names, dependencies, optional dependencies.
  • Any other comments?

Making the world a better place, one line of code at a time! 🙂

The tools are here.

New project home page: Maven Tools 4 Eclipse

7 Comments | Software | Tagged: , , , , | Permalink
Posted by digulla

Project Dash m4e Tools – Create Maven Artifacts From Eclipse Plug-ins

18. March, 2011

[UPDATE] There is now a testing repo which contains Eclipse 3.6.2

If you use Maven and Eclipse, you know the pain: How do I convert Eclipse plug-ins into Maven artifacts?

The simple step is to run mvn eclipse:make-artifacts (or the ill fated eclipse:to-maven).

But that’s only half of the work. A few of the plug-ins have bad dependencies (stuff isn’t declared optional, polluting your runtime classpath; versions of dependencies are missing). And a major problem is source attachments. Eclipse separates those from the binaries, so you end up with org.eclipse.core.runtime and org.eclipse.core.runtime.sources.

A few days ago, bug 337068 – “Please set up maven.eclipse.org” was fixed. The site exists and there is even a Nexus running on it.

Unfortunately, it’s a bit empty for now. We’re working on it 🙂

One of the first steps is a set of tools that takes downloads from eclipse.org and converts them into proper Maven artifacts – with source and all.

Welcome Project Dash m4e Tools. A preliminary version is available on github: https://github.com/digulla/org.eclipse.dash.m4e.tools

It consists of three tools so far:

  1. m4e-import can import downloads (archived or unpacked) into a temporary Maven 2 repository. Your own local repository (${user.home}/.m2/repository) is left untouched!
  2. m4e-merge can merge several a temporary Maven 2 repositories into one.
  3. m4e-attach-sources tries to find all source bundles, moves+renames the source JAR to the right place and name and deletes the unnecessary folder.

Next step is a tool to patch the artifacts. One open issue is: How to handle dependencies which come from Project Orbit (bundling third party libraries for Eclipse projects).

Please visit Bug 340416 – “Resolving dependencies from Project Orbit” if you have an opinion.

6 Comments | Software | Tagged: , , , , , | Permalink
Posted by digulla

Building RCP Apps With OSGi

16. March, 2011

Dave Orme wrote a really interesting article about building blocks of a RCP application with OSGi: The OSGi Building Block Pattern: An Invitation

I agree with him: The RCP wizard should really create projects to build a p2 repo and to package the bundles and features into something that a user can download and install.

Right now one of the major stumbling blocks when starting with Eclipse projects is that they either don’t build at all or that I fail to bundle/package them into some “output.”

The typical situation is that I’ve managed to import the project into my workspace. Now I get a lot of compile errors because bundles are missing in my IDE. Problem: I see the names but I have no idea at all where to download them. (See bug 340014 – “Offer a quick fix to install missing dependencies from p2 repositories”)

After manually googling for bundle names, trying to find the p2 repo which might contain them (in former times, p2 repositories offered a way to quickly browse them with a web browser – that doesn’t work anymore, so it’s poking in the dark). After a couple of restarts, the compile errors are gone.

At long last, I can start to fix my problem.

But now what? How can I create the “thing” that I need? (where “thing” can be a RCP app, a p2 repo, a bundle, a feature). Eclipse doesn’t allow to save the final after-build-step anywhere. Users must remember the steps: Export…, select the correct tool out 500, fill out the 100+ options in the little dialogs that pop up, rinse, repeat.

Welcome bug 340018 – “Allow to save export actions in a “launch” config”

Leave a Comment » | Software | Tagged: , , , , , | Permalink
Posted by digulla

TNBT – Object Teams

15. March, 2011

Object Teams, or OT/J for short, is a solution for the old Java problem “there is no I in ‘team'”: Most Java code is written as if the whole world was openly hostile. It’s riddled with final, private static, singletons, thousands of lines of code which almost do what you need except for this one line .. that you can’t change without copying the other 999.

Groovy’s solution: AST transformation. A topic for another post.

OT’s solution: create a Java-like programming language which allows you to extend code that isn’t meant to. A great example: Extending Eclipse’s Java compiler.

The Eclipse Java compiler is one of the most complex pieces of code in Eclipse (“5 Mbytes of source spread over 323 classes in 13 packages“). Unlike other compilers, it can compile broken code. The same technology is used to create byte code and error markers in the editor.

Stephan Herrmann wanted to add support for @NonNull and @Nullable. Usually, you’d create a branch, keep that branch in sync with the main branch, etc. Tedious. For every change that someone makes in the main branch, you must update your development branch. Even if the change is completely unrelated. CVS has a very limited concept of “related”. DVCS like Git or Mercurial are better at merging but they also don’t understand enough of Java to give the word “related” a useful meaning. “Same file” is the best you can get.

So instead of the tedious way, he used OT/J to create an OT/Equinox plug-in which patches the JDT compiler byte code. Sounds dangerous? Well, OT/J does all the ugly work. You just say “when this method is called, do this, too.” Sounds a bit like AOP? Yes.

Unlike AOP, it communicates intent more clearly. The code wasn’t designed to be the most compact way to define a “point cut” and then leave it to the reader to understand what this is supposed to mean. It better communicates the intent.

I’m not completely happy with the syntax, though. I don’t have specific points, only a general wariness. Maybe a careful application of Xtext would help.

Related Articles:

  • The Next Best Thing – Series in my blog where I dream about the future of software development

Leave a Comment » | Software | Tagged: , , , , , , , , | Permalink
Posted by digulla

« Previous Entries
Next Entries »