Complete
over 3 years ago

Barrel/jungle documentation is unclear

1)

The jungle documentation says

> Qualifiers have six properties that can be referenced by following a qualifier with a dot (.) and a property name:

and then lists the six properties, including "annotations". But in fact, "annotations" can't be applied to a qualifier - at least, not in the same sense as the other 5. The only way to use "annotations" is as

qualifier.BarrelName.annotations = <whatever>

Where BarrelName is one of the barrels identified in the manifest file. It's also odd that the only thing that can come after qualifier.BarrelName seems to be "annotations" (so why not just drop the .annotations part?). Anything else results in a syntax error - and a very badly worded one too. eg

qualifier.BarrelName.excludeAnnotations = <whatever>

ERROR: monkey.jungle:7: mismatched input 'excludeAnnotations' expecting {'.', '-', ID, DIGIT, 'manifest', 'sourcePath', 'excludeAnnotations', 'resourcePath', 'lang', 'barrelPath', 'annotations'}

So the error says it found excludeAnnotations, when it was expecting one of a number of things. But one of the things it says it was expecting is excludeAnnotations!

2)

The way annotations work is unclear.

It’s also possible to use the annotations qualifier property to import select, annotated portions of a barrel. This is useful when a Barrel contains a library of classes and methods, but an application only needs to use a fragment of the library. For example, assume the GraphLibrary barrel imported above contains several different graphing methods, but an application only needs to use a bar graph. The Barrel author was kind enough to annotate each method, so rather than using the entire Barrel, we can limit imported code to only those methods that are needed:

It sounds like this is saying that by default you would import the entire library, but that you can use annotations to just import the parts you need. But as far as I can tell, if you don't specify any annotations (for a barrel that has some defined in its manifest), you get nothing (or just the unannotated parts - but unannotated parts result in compile time warnings). So if you want the whole thing, you need to know the full list of annotations, and specify them all. In the case of a third-party .barrel you would have to unzip it, and look at the manifest to find this list...

3)

I already asked this question, and nobody seems to have an answer, so maybe putting an actual example with code would help? In particular is this (more than one barrel path for a single barrel) something that can only be done with barrel projects, rather than .barrel files? And what happens if there's overlap between the jungles. ie both jungles pull in the same resource, or source file? Is it an error, or do you just get one copy?

4) There are broken links in the document, eg

Take a look at the [Monkey Barrels](/connect-iq/core-topics/shareable/ Libraries#shareablelibraries) chapter to learn more about Monkey Barrels and how they can be used.

5) The shareable libraries page still talks about the eclipse plugin, even though the instructions immediately following only talk about VSCode.

6) The instructions for creating a new barrel in VSCode includes "Select the minimum API level" (and VSCode does in fact prompt for this). When you're done though, and try to build the barrel you just created, you get an error because minimum code version isn't allowed in a barrel manifest, and you have to manually remove it.

markw65
  • over 3 years ago

    So I think I figured out 3), and the problem is that the documentation seems to be very misleading, if not completely wrong.

    If you have a barrel project, and the build command uses two or more jungle files (eg monkeyC.jungleFiles=round.jungle;rectangle.jungle), then when you include that as a barrel project, you have to do it as

    qualifier.barrelPath=[roundIcons.jungle;rectangleIcons.jungle]

    because without the [] the compiler thinks you're giving it paths to two separate barrels, rather than a single set of build commands for one barrel.

    But that *doesn't* mean that a developer that only wants the "round" part can include round.jungle, and one that only wants the rectangle part can include rectangle.jungle, because only one of those jungle files can have a project.manifest declaration. So including the other by itself will never be legal.

    Perhaps the documentation assumes that roundIcons.jungle is self contained, and so can be used alone, and rectangleIcons.jungle is an "add-on" that adds some more things. But the way it's written seems to imply that you can freely pick and choose round, rectangle or both. This really needs to be clarified, together with explaining exactly what the syntax means.