Fill in a small amount of details on the jib-as-a-library proposal

proposals/jib_core_library.md

@@ -8,16 +8,32 @@ Design for Jib Core as a Java library for building container images.
 
 # Proposed API
 
+## General Containers
+
 `Jib` - the main entrypoint for using Jib Core
-- `JibContainerBuilder from(String baseImageReference)`
-- `JibContainerBuilder from(ImageReference baseImageReference)`
-- `JibContainerBuilder from(RegistryImage baseImage)`
+
+- `static JibContainerBuilder from(String baseImageReference)`
+- `static JibContainerBuilder from(ImageReference baseImageReference)`
+- `static JibContainerBuilder from(RegistryImage baseImage)`
 
 `JibContainerBuilder` - configures the container to build
-- `JibContainerBuilder addLayer(List<Path> files, Path pathInContainer)`
+
+- `JibContainerBuilder addLayer(List<Path> files, String directoryInContainer)`
+
+ Adds a new layer that will consists of the files referred to by `files`, each of which is copied into the `directoryInContainer`. Regardless of the directory nesting of files in `files`, they will be copied into the same level inside the container. Each `Path` object in `files` must represent a file, not a directory.
+
+ ```java
+ container.addLayer(
+ Arrays.asList(
+ Paths.get("/a/b/c.txt"),
+ Paths.get("/a/b.txt"),
+ Paths.get("/a/c.txt")),
+ "/root");
+ // container will have /root/b.txt, and /root/c.txt (from /a/c.txt)
+ ```
+
 - `JibContainerBuilder addLayer(LayerConfiguration)`
 - `JibContainerBuilder setLayers(List<LayerConfiguration>/LayerConfiguration...)`
-
 - `JibContainerBuilder setEntrypoint(List<String>/String...)`
 - `JibContainerBuilder setProgramArguments(List<String>/String...)`
 - `JibContainerBuilder setEnvironment(Map<String, String> environmentMap)`
@@ -31,15 +47,18 @@ Design for Jib Core as a Java library for building container images.
 Three `TargetImage` types (`RegistryImage`, `DockerDaemonImage`, and `TarImage`) define the 3 different targets Jib can build to.
 
 `RegistryImage` - builds to a container registry
+
 - `static RegistryImage named(ImageReference/String)`
 - `RegistryImage addCredential(String username, String password)`
 - `RegistryImage addCredentialRetriever(CredentialRetriever)`
 
 `DockerDaemonImage` - builds to a Docker daemon
+
 - `static DockerDaemonImage named(ImageReference/String)`
 - `DockerDaemonImage setDockerExecutable(Path)`
 
 `TarImage` - builds to a tarball archive
+
 - `Builder`
  - `TarImage saveTo(Path outputFile)`
 - `static Builder named(ImageReference/String)`
@@ -52,25 +71,45 @@ Three `TargetImage` types (`RegistryImage`, `DockerDaemonImage`, and `TarImage`)
 - `Containerizer setCacheConfiguration(CacheConfiguration)`
 - `Containerizer setEventHandlers(EventHandlers)`
 
-## For Java containers
+## Simple example
+
+```java
+Jib.from("busybox") 
+ .addLayer(Arrays.asList(Paths.get("helloworld.sh")), "/") 
+ .setEntrypoint("/helloworld.sh")
+ .containerize(
+ Containerizer.to(RegistryImage.named("coollog/jibtestimage")
+ .setCredential("coollog", "notmyrealpassword")));
+```
+
+# For Java containers
+
+`JavaContainerBuilder` - builds a `JibContainerBuilder` for Java apps. 
 
-`JavaContainerBuilder` - builds a `JibContainerBuilder` for Java apps
 - `static JavaContainerBuilder builder()`
 - `JavaContainerBuilder addDependencies(List<Path> dependencyFiles)`
 - `JavaContainerBuilder addResources(List<Path> resourceFiles)`
 - `JavaContainerBuilder addClasses(List<Path> classFiles)`
 - `JavaContainerBuilder addToClasspath(List<Path> otherFiles)`
 - `JavaContainerBuilder setJvmFlags(List<String>/String... jvmFlags)`
 - `JavaContainerBuilder setMainClass(String mainClass)`
-- `JavaContainerBuilder toContainerBuilder()`
+- `JibContainerBuilder toContainerBuilder()`
 
-# Simple example
+ Returns a `JibContainerBuilder` that, when built, will produce a minimal Java image that executes the java application specified by the builder methods previously called on this `JavaContainerBuilder`. 
 
-```java
-Jib.from("busybox")
- .addLayer(Arrays.asList(Paths.get("helloworld.sh")), "/helloworld.sh")
- .setEntrypoint("/helloworld.sh")
- .containerize(
- Jib.to(RegistryImage.named("coollog/jibtestimage")
- .setCredential("coollog", "notmyrealpassword"));
-```
+ Example:
+
+ ```java
+ RegistryImage destination = RegistryImage.named("gcr.io/myuser/my-java-container:latest");
+
+ JibContainerBuilder javaImage = JavaContainerBuilder.builder()
+ .addDependencies(Lists.newArrayList(Paths.get("/my/filesystem/lib/my-dependency.jar"))) 
+ .addClasses(Lists.newArrayList(Paths.get("/my/filesystem/target/com/google/FooMain.class")))
+ .setMainClass("com.google.FooMain")
+ .toContainerBuilder()
+ // Add other customization to the image, maybe some labels
+ .addExposedPort(Port.tcp(8080));
+
+ // Throws an exception if the image couldn't be build.
+ JibContainer result = javaImage.containerize(Containerizer.to(destination));
+ ```