Xtext Grammar for. bnd-Files

[Florian Pirchner]

Dear BndTools-Team,

i really like BndTools. In the past we setup all our customer projects based on PDE.

And for the next customer project we are looking forward to use BndTools.

For now i have been writing an OpenSource project based on BndTools and it works properly fine ;)

But there is one issue i am struggling with. It's the way how to write the .bnd and .bndrun files. Mostly i copied stuff from enRoute,... and did trial and error approach.

I was reading the documentation a few times, but honestly i am not sure, how to use the different keywords in the files.

For instance some of the keyword like "-augment" use a "-" prefix. But "debug-bundles" does not so.

And you can extend the keyword - sometimes - with a doted prefix. Like "-plugin.enroute.distro".

Honestly, it is not that simple to write the .bnd files. You need to know a lot details about it.

So i came up with an idea. What would you think about an Eclipse plugin based on Xtext? Providing keywords, content assist, validation, cross references,...

For instance, the following plugin definition would be content assisted based for 100%.

-plugin.vaadin: \
\
aQute.bnd.repository.maven.provider.MavenBndRepository; \
releaseUrl= http://repo1.maven.org/maven2/; \
index=${.}/vaadin.maven; \
readOnly=true; \
name="Vaadin"

And most / all of the definitions should be so. And it should be possible, that anybody providing a new definition for anything, can provide a simple "grammar snippet". Creating these snippets should be pretty simple for everyone.

I will start with a first prototype in a few weeks.

And I already talked to an Xtext expert. He is interested in contributing. We will meet in a few month (July, August) to find out, if Xtext could do this job.

Right now it is not sure, whether Xtext can do this job. Specially according the "grammar snippets". We need to figure out.

What do you think about this idea? Having an "extendable" Xtext Grammar which supports the creation of .bnd files?

Thanks for answers...

Best Florian

[Raymond Auge]

I personally think this would be a great idea.

One thing to note is that there is "some" documentation for rules around headers and instructions which you can find in the bnd documentation. It's a little hard to locate, but it does exist! :) A brief rundown is:

Headers: Headers always start with an uppercase letter.

e.g.

Bundle-Version: # an OSGi spec header

X-Some-Foo: # a custom header (X- is just convention, but doesn't need to be added really)

Instructions: instructions always start with `-`.

e.g.

-runbundles:

-trace:

Temporary variables: temporary variables always start with a lower case letter and are not included in output in the manifest.

e.g.

debug-bundles: # some temporary value, which can be referenced by name in header values, instructions, other variables and macros.

Furthermore, there's also already some "editor hints" for many of the instructions and headers available in the bnd editor. However, I often find things that are missing or are poorly described. For instance, as you mentioned, certain instructions do not explain that they are "mergable" (meaning that they can be namespaced for convenience and readability). It would be great to expand this already existing resource.

In general though I think no one would object to improving the bnd file editors :)

Sincerely,

- Ray

--
You received this message because you are subscribed to the Google Groups "bndtools-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to bndtools-users+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

--

Raymond Augé (@rotty3000)

Senior Software Architect Liferay, Inc. (@Liferay)

Board Member & EEG Co-Chair, OSGi Alliance (@OSGiAlliance)

[BJ Hargrave]

Bnd files are java properties files. See http://bnd.bndtools.org/chapters/790-format.html.

By convention:
- property names starting with an Upper case letter are put in the resulting manifest. See http://bnd.bndtools.org/chapters/800-headers.html.

- property names starting with '-' are Bnd instructions. See http://bnd.bndtools.org/chapters/820-instructions.html and http://bnd.bndtools.org/chapters/825-instructions-ref.html.

- Other property names are just variables which can be referenced by ${var}.

Bnd also has a set of macros which are functions. See http://bnd.bndtools.org/chapters/850-macros.html.

Note, like any open source project, the documentation is not always complete. I am sure there are instructions and macros in bnd which are not documented. Another wrinkle is that some instructions and macros only work in certain contexts. Bnd supports the Bnd Workspace build model and also non-workspace build models like maven where there is no Bnd Workspace object or Bnd Project object.

As for an XText grammar, we add new macros and instructions from time-to-time as we add new features. So keeping the grammar up to date will be a challenge. Also the issue with what works in what context will also be a challenge.

--
You received this message because you are subscribed to the Google Groups "bndtools-users" group.

To unsubscribe from this group and stop receiving emails from it, send an email to bndtools-user...@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

BJ

[Florian Pirchner]

Hey Ray,

thanks a lot for this introduction... I will start to look for the the documentation about the grammar :)

And cool... So i will start with an Xtext editor in a few weeks, when current project is implemented. I already implemented about 15 Xtext grammars. So i got a good idea about it.

Best Florian

[Florian Pirchner]

Got another question.

Are bnd-files based on a common format (grammar)? Like YAML, Properties,...

And if yes, how is it called. I am pretty sure, that github provides a BNF licensed under the Apache v2 for it, if it is a common format.

Thanks, Florian

[Neil Bartlett]

As BJ said two messages ago, they are Java Properties files. 

The javadoc for java.util.Properties thoroughly documents the grammar. 

Neil

[Florian Pirchner]

Oh sorry!

I missed the mail from BJ somehow. Working on the web client at home. So happened... Sorry for that!

And thanks a lot!

[Florian Pirchner]

Hey BJ,

thanks for the information.

And you are right. Keeping the Grammar up to date is a challenge. So we need to have "grammar snippets" working. It should be very easy to provide them. 

And yep. Different contexts mean different scopings.

In my opinion, the way to provide new "grammar snippets" for new makros and instructions should be very easy and transparent to people writing them. They should not have to struggle with Xtext-Grammar. 

The integration into the "Main Xtext Grammar" should work on the fly. I really like the style of OSGi-Spec, when formats are defined. It is very common known and easily to understand. So maybe this would be a base to define new stuff.

I need to think a lot about it... And honestly, right now I am not sure, if Xtext can do this job?!

Thanks,

Florian

To unsubscribe from this group and stop receiving emails from it, send an email to bndtools-users+unsubscribe@googlegroups.com.

For more options, visit https://groups.google.com/d/optout.

--

BJ

--

You received this message because you are subscribed to the Google Groups "bndtools-users" group.

To unsubscribe from this group and stop receiving emails from it, send an email to bndtools-users+unsubscribe@googlegroups.com.

[Peter Kriens]

The current Eclipse editor is controlled from the bndlib. There is a Syntax class that contains (or is supposed to contain) very detailed information about all headers and instructions. It would be great if you could fetch these details from bndlib so that in other environments we have this meta information about the commands in one place. I.e. would like not to have a lot of detailed knowledge about bnd in another program.

Overall, it would be nice to have an editor that would recognise the syntax of the headers. We might support a format in the future where we properly parse the file so that you do not need the \ to make it a single line.

Kind regards,

Peter Kriens

To unsubscribe from this group and stop receiving emails from it, send an email to bndtools-user...@googlegroups.com.

[Florian Pirchner]

Hey Peter,

thanks a lot for this input. I will take this issue to the list of requirements...

Right now i am not sure, if Xtext can do this job.

So i will go and write a prototype finding out...

Thanks Florian