docs: system dependencies are not always available #191
Conversation
content/apt/guides/introduction/introduction-to-dependency-mechanism.apt
Outdated
Show resolved
Hide resolved
| This scope is similar to <<<provided>>> except that you have to provide the JAR | ||
| which contains it explicitly. The artifact is always available and is not | ||
| looked up in a repository. | ||
| Maven does not add system-scoped dependencies to any classpath. |
There was a problem hiding this comment.
I do not agree with this. @rfscholte
There was a problem hiding this comment.
There's probably no need for this scope anymore, so I would be very explicit about the history of system-scope. AFAIK system-scope was there for jars that were available in the JDK, but not in the JRE even though were required to do the build.
I'd avoid the word 'classpath', it is higher in the hierarchy although accessible via the classpath, see https://www.baeldung.com/java-classloaders
There was a problem hiding this comment.
It is unfortunately that easy and it is not just the JDK
- https://issues.apache.org/jira/browse/MNG-1867
- https://issues.apache.org/jira/browse/MNG-6523
- The idiot's from SAP have hardoded the JCo JAR name and it won't start if you rename it
- JAR which people aren't allowed for reasons to upload to a local repo instance
- likely others
There was a problem hiding this comment.
I'm missing some context: what was the reason to change the original text? If we want to avoid the usecases, just explain how it works: a provided-scoped artifact will be used from the local repository during compile time, at runtime it is assumed to be there. A system-scoped artifact should be available on the system during both compile time and runtime.
There was a problem hiding this comment.
It's been a while but this came up a couple of projects ago in my then day job, where we spent a lot of effort untangling different kinds of dependency scopes and analyzing dependency graphs. The existing text is wrong in one key respect:
"Dependencies with the scope system are always available and are not looked up in repository."
However, dependencies with the scope system are not "always available". Declaring a dependency such as
<dependency>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-site-plugin</artifactId>
<version>4.0.0-M7</version>
<scope>system</scope>
</dependency>
doesn't magically make it available. This is likely just sloppy writing, and the intent was to document the correct behavior but that's not how the text reads currently, especially to a dev not steeped in Maven dependency management.
Let me take another stab at rephrasing this to take into account the points you bring up about non-classpath based resolution of dependencies.
|
Ping @rfscholte I still think this doc change is needed. The current documentation is simply incorrect. |
|
LGTM |
| The system scope is commonly used to tell Maven about dependencies provided by the JDK or the VM. | ||
| System dependencies are especially useful for resolving dependencies on artifacts which | ||
| are now provided by the JDK, but were available as separate downloads earlier. Typical | ||
| examples are the JDBC standard extensions or the Java Authentication and Authorization |
There was a problem hiding this comment.
I don't even know whether the cae with JDBC and JAAS is still true. I'd try to avoid giving example which are invalid in a couple of years.
There was a problem hiding this comment.
I think it is. Per Oracle docs, "The Java Authentication and Authorization Service (JAAS) was introduced as an optional package (extension) to the Java 2 SDK, Standard Edition (J2SDK), v 1.3. JAAS was integrated into the J2SDK 1.4." Unless Oracle decides to remove it again, this statement seems likely to be true for the indefinite future.
Though now that I think about it, I don't really see how this helps to to tell Maven about dependencies provided by the JDK or the VM. If you're in a VM that includes them, this is unnecessary and if you're not then a system dependency doesn't help since it's not there. Maybe if you're compiling with JDK 1.5 but targeting 1.3 or something like that?
There was a problem hiding this comment.
Even if, i don't know wether this really helps.
There was a problem hiding this comment.
I'm OK with removing this paragraph completely. The case that makes me pause is tools.jar. If I recall correctly that is not in the VM and also is not available from the Maven repo system. Is there any way to load that that is not a system dependency?
There was a problem hiding this comment.
I think if you custom-bundle Maven with your deps, e.g., extensions or so.
There was a problem hiding this comment.
I'm not quite sure what you mean. Do you mean some sort of fat jar? Or perhaps a custom version of Maven? Either way this seems much more complex than a system dependency that points to tools.jar.
To move this PR forward, what specific change in the current text do you propose?
There was a problem hiding this comment.
My example was just have a custom JAR which you distribute across your company. That's it.
My proposal is to simply remove all examples regarding system and provide an abstract description/definition of this feature.
@michael-o