Some help needed about .proto shipped as ZIPs

[cdprete]

Hello.

I'm trying to follow https://ascopes.github.io/protobuf-maven-plugin/dependencies.html#a-simple-example but I'm failing to understand how it work and/or how to use it.

Setup:

• a project A has a a.proto that gets packaged as A-<version>-proto.zip and the structure in the ZIP is A/a.proto.
• a project B has a b.proto that depends on a.proto. For this, b.proto defines a import A/a.proto and adds the ZIP as Maven dependency.

The problem I've is that, during the compilation of the sources of B, Maven can't find the sources of A.
I think, but I hope that's not the case, the issue may be caused by the fact that a.proto defines option java_package = "foo.a"; which doesn't really match the folder structure in the ZIP.
I also see a

warning: Import A/a.proto is unused.

If I use, instead, this then it works but the import is still ignored.
I can see, though, that a.proto is then available under target/protobuf-maven-plugin/generate/generate/archives/A-<version>-proto-<sha>/A/.
@ascopes your help would be appreciated :)

[ascopes]

The protobuf imports should correspond to the protofile paths, so should totally ignore whatever the requested Java package is. The important bit is the regular "package" directive.

E.g.

# in baz/bar/foo.proto

package abc;

message Foo {
   ...
}

...for this, your import elsewhere should be

import "baz/bar/foo.proto"

message Something {
  abc.Foo foo = 1;
}

Can you confirm the package names are being used correctly, or share a snippet with any redacted naming?

[cdprete]

Btw, I've fixed the names for the imports in there to match what's described in here and now I've the same error even without Java sources:

[ERROR] Failed to execute goal org.apache.maven.plugins:maven-compiler-plugin:3.14.0:compile (default-compile) on project appb: Compilation failure: Compilation failure:
[ERROR] /C:/Daten/gitlab/demo/app-b/target/generated-sources/protobuf/foo/timeseriesapi/proto/HelloWorldProto.java:[59,29] package foo.adjustmentsapi does not exist
[ERROR] /C:/Daten/gitlab/demo/app-b/target/generated-sources/protobuf/foo/timeseriesapi/proto/HelloWorldProto.java:[74,23] package foo.adjustmentsapi does not exist

[cdprete]

Thanks, just taken a look.

The two app directories need child POMs so they are separate Maven modules, would you be able to include those in however you have this set up? Thanks!

Ok, I got it now. For some reason, they were not added in git. Sorry for that. It's fixed now.

[ascopes]

Aha. adjustmentsapi.proto needs to be in a nested directory named "appa".

src/main/protobuf/appa/adjustmentsapi.proto

rather than

src/main/protobuf/adjustmentsapi.proto

[cdprete]

Why? In the ZIP it's indeed in such a nested folder.

[ascopes]

Ah just spotted that when I ran it locally, missed the fact you override the base dir.

For clarity though it may be worth mirroring the structure as mentioned, although in this case it is definitely not the issue.

[ascopes]

Ok so the issue is that you are depending on the proto files as imports. This assumes you have the corresponding Java classes in that dependency as well if you wish for Java to be able to see them. I probably should go and update that example to make it a little clearer when I have some time.

If you look at protobuf-java, you'll observe they package both the protobuf sources and the corresponding classes. This is also the reason why I do not recompile proto sources that were added as a dependency by default.

Sorry for the confusion, I thought you were meaning that protoc was failing to resolve them rather than protoc only feeding out the sources for your direct dependencies.

In your case there are a few options:

1. distribute as a JAR and include the proto sources too. You can do that with the regular JAR packaging in your POM rather than using the assembly plugin. Then enable embedSourcesInClassOutputs at https://ascopes.github.io/protobuf-maven-plugin/generate-mojo.html#embedSourcesInClassOutputs.
2. explicitly ask protoc to compile those sources like you mentioned by passing the zip in the plugin configuration rather than as a project dependency. that is the correct way to also compile dependencies.
3. distribute a descriptor file instead... see https://ascopes.github.io/protobuf-maven-plugin/descriptor-files.html for how to use them.

[ascopes]

I think for your use case as I mentioned in the second message, what you are really looking for is shading. That'll provide the best way for users to consume anything you distribute without having to rely on specific toolchains to recursively manage dependencies

[cdprete]

Ok, I tried to use descriptors today, but I still can't figure out then how can I in a proto file X say that I want to import the definitions of one of those dependencies.

This

import "timekeepers/adjustmentsapi/v1/adjustments.proto";

now for some reason it doesn't fail, but IntelliJ can't find it and protoc issues a warning about this being not used.
So, I wonder, where is it? It's not under target or wherever in the project itself.

Do you have an example about shading? I know that both the assembly plugin and the shade plugin can be used for this, but what should be the structure?

[ascopes]

I don't have an example of shading to hand, but effectively everything should be in the root directory of the archive, then nested in the subdirectories like they are in the separate ZIPs you have built.

Unused

Are you referencing the things you are importing in that file? In the examples you showed yesterday, nothing was using what you imported, if I recall.

[cdprete]

Are you referencing the things you are importing in that file? In the examples you showed yesterday, nothing was using what you imported, if I recall.

That's correct.

I don't have an example of shading to hand, but effectively everything should be in the root directory of the archive, then nested in the subdirectories like they are in the separate ZIPs you have built.

Ok, I can try to give it a try if I've some time.

[ascopes]

That unused warning is most likely to be expected in that case.

[cdprete]

Yep, indeed. It's more about IJ not finding them, but I'll probably need the shade for it. The descriptor doesn't help, it seems like. Il ven 3 ott 2025, 09:15 Ash ***@***.***> ha scritto:

…

That unused warning is most likely to be expected in that case. — Reply to this email directly, view it on GitHub <#818 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACAZGWFUJFFG5YQG7EUH2QT3VYPC3AVCNFSM6AAAAACH73AMQSVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTINJYGEYTEOI> . You are receiving this because you authored the thread.Message ID: <ascopes/protobuf-maven-plugin/repo-discussions/818/comments/14581129@ github.com>

[ascopes]

The issue with IntelliJ is likely going to be persistent regardless of what you do. As far as I am aware, they do not cater for detection of proto sources based on how this Maven plugin operates (and I don't believe they will handle descriptors either).

You could possibly raise this with the vendor of the plugin you are using (there are three or four options if I recall).

[ascopes]

Raised GH-824 to try and improve the exception messages from HTTP URLs we discussed here somewhere (I cannot find the thread where I mentioned I'd try to improve those).

[ascopes]

Did you manage to resolve your issue?

[cdprete]

Not completely given that IDEA still doesn't resolve the imports, but I can live with that.

[ascopes]

I'd suggest raising a YouTrack issue for IntelliJ if you are able. Would be nice to find out if they have any difficulties with what I am exposing via m2e that I can tweak to improve their integration.