rmuir commented on code in PR #16584: URL: https://github.com/apache/lucene/pull/16584#discussion_r3893240874
########## help/dependencies.md: ########## @@ -0,0 +1,128 @@ +# Dependencies + +Each gradle project can have multiple (named) "configurations" and each configuration can have dependencies attached +to it. + +There are some standard conventions so, for example, the Java plugin adds standard configurations such as `api`, +`implementation`, `testImplementation` and others. These configurations can also inherit from each other; more about +this topic can be found here: + +- <https://docs.gradle.org/current/userguide/dependency_management_for_java_projects.html#dependency_management_for_java_projects> +- <https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation> +- <https://docs.gradle.org/current/userguide/java_plugin.html#sec:java_plugin_and_dependency_management> + +Lucene uses the following configurations and attach project dependencies to them: + +- `moduleApi` - makes the dependency available to main classes, tests and any other modules importing the project (exportable dependency), +- `moduleImplementation` - makes the dependency available to main classes, tests but will *not* export the dependency to other modules (so their compilation classpath won't contain it). +- `moduleTestImplementation` - makes the dependency available for test classes only. + +The `module` prefix is used to distinguish configurations which apply to modular builds, compared to the regular +classpath-configurations defined by gradle's java module. Some Lucene modules may define regular classpath entries to +bypass the limitations of the module system (or gradle's). + +## Adding a library dependency + +Lucene dependencies and their versions are managed globally using version catalogs (in `gradle/libs.versions.toml`) +<https://docs.gradle.org/current/userguide/platforms.html>. + +Let's say we wish to add a dependency on library `foo.bar:baz` in version 1.2 to `:lucene:core`. Let's assume this +library is only used internally by the project. The `:lucene:core` project is configured by `lucene/core/build.gradle`, +so we add (or modify) the dependency block as follows: + +```groovy +dependencies { + moduleImplementation deps.baz +} +``` + +The `moduleImplementation` here is a named configuration explained in the section above. The `deps.baz` refers to the +version catalog named `deps`, in which the dependency `baz` should be declared. If this is the first reference to this +library, then we have to add it to `versions.toml` catalog: the version goes under the `versions` and module +coordinates under the `libraries` section: + +```toml +[versions] +baz = "1.2" +... +[libraries] +baz = { module = "foo.bar:baz", version.ref = "baz" } +``` + +The version defined in the `versions` section is the preferred version of the library we wish to use. Finally, run +tidy to sort all entries in `libs.versions.toml`: + +```shell Review Comment: I think all these `shell`'s should be changed to explicit `sh`, `bash`, or `zsh`, so that there's a language to highlight. Otherwise you don't get any or correct syntax highlighting. I can clean it up afterwards though. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
