renamed container_inject to container_layer; updated commented example

Author: SIGUSR2

containers.build_defs

@@ -93,7 +93,7 @@ def container_flattener(name:str, srcs:list, toolchain:str = CONFIG.PLEASE_CONTA
         },
     )
 
-def container_inject(name:str, srcs:list, destination:str, toolchain:str = CONFIG.PLEASE_CONTAINERS_TOOLCHAIN, visibility:list=[], labels:list=[]):
+def container_layer(name:str, srcs:list, destination:str, toolchain:str = CONFIG.PLEASE_CONTAINERS_TOOLCHAIN, visibility:list=[], labels:list=[]):
     dst = destination.lstrip('/')
     datefmt = '+%Y-%m-%dT%H:%M:%S%z'
 
@@ -129,8 +129,6 @@ def container_inject(name:str, srcs:list, destination:str, toolchain:str = CONFI
             'sha256': [ toolchain+'|sha256'],
             'jarcat': [ CONFIG.JARCAT_TOOL ],
         },
-        # deps = [ baseimage ],
-        # post_build = lambda name, output: [add_out(name, line) for line in output if line]
     )
 
 def container_config(name:str, srcs:list, timestamp:str='0', toolchain:str = CONFIG.PLEASE_CONTAINERS_TOOLCHAIN, description:str = '', image_labels:dict = {}, entrypoint:list = [], command:list = [], environment:dict = {}, ports:list = [], osversion:str = 'linux', architecture:str = 'amd64', visibility:list = ['PUBLIC'], labels:list=[]):
@@ -192,7 +190,6 @@ def container_config(name:str, srcs:list, timestamp:str='0', toolchain:str = CON
 # CLOUDSDK_CONFIG has to point to the $HOME/.config/gcloud directory, otherwise push will fail;
 # DOCKER_CONFIG has to point to a $HOME/.docker with configured docker credential/helper for gcr.io cases or some other auth completed already for private repos;
 # if the docker-credential-gcloud is being used, it has to be symlinked into the limited PATH used by please - either /usr/local/bin or /usr/bin
-# TODO: find a way to remote the unnecessary output
 def container_push(name:str, srcs:list, repository:str = CONFIG.DEFAULT_DOCKER_REPO, tag:str = '', image_name:str = '', toolchain:str = CONFIG.PLEASE_CONTAINERS_TOOLCHAIN, visibility:list = ['PUBLIC'], labels:list=[]):
     outfile = f"{name}_run.sh"
     fqnfile = f"{name}_fqn"

examples/BUILD

@@ -17,55 +17,63 @@ filegroup(
     ]
 )
 
+# DESCRIPTION:
+# * name            Mandatory - name of the rule
+# * image           Mandatory - which image to pull
+# * tag             Mandatory - which image version to pull
+# * repository      Optional (default = "index.docker.io")
+# Pull an image from the registry and save it for future use; 
+
 container_pull(
     name = 'ubuntu',
     image = 'ubuntu',
     tag = '20.04',
 )
 
+# DESCRIPTION: 
+# This rule's srcs MUST be a multi-layer container_pull rule; it creates a container one with a single merged layer
+
 container_flattener(
     name = 'ubuntu_flat',
     srcs = [ ":ubuntu" ],
 )
 
-# container_inject just copies a bunch of files from another please target into a separate layer; 
-# it may be repeated as many times as there are files
-# all files are being copied in the same destination directory
-# all files receive 755 if they are generated by a binary rule or 664 if not, with ownership nobody:nogroup
-# 
-# supported arguments (and defaults or suggested values)
-# name:                     descriptive
-# baseimage: <target>       a previous container_pull or container_flattener target
-# srcs: []                  list of targets that contain or generate the files to be copied
-# destination: <path>       where to put those files
+# DESCRIPTION:
+# * name             Mandatory. The name of the rule
+# * srcs             Mandatory. The list of targets that generate the file or files to be included. 
+# * destination      Mandatory. The destination directory. 
+# All files inserted into the layer will be 
+# * owned by nobody:nogroup
+# * mode 644 if they come from a normal please rule
+# * mode 755 if they come from a rule marked as "binary"
+# * placed in the same directory; if different destinations are required, one must define multiple rules
 
-container_inject(
+container_layer(
     name = 'ubuntu_files',
     srcs = [ ":inject" ],
-    # baseimage = ":ubuntu_flat",
     destination = "/opt/foo",
 )
 
-container_inject(
+container_layer(
     name = 'ubuntu_files_two',
     srcs = [ ":inject_two" ],
-    # baseimage = ":ubuntu_files",
     destination = "/opt/bar",
 )
 
-# container_config runs after inject or flatten and creates the required metadata files for the container
-# supported arguments (and defaults/suggested values)
-# name: descriptive
-# baseimage: <target>       previous container_flatten or container_inject target
-# description: ''           what will be the description of the container (optional)
-# image_labels: {}          what labels to associate with the container (optional)
-# environment: {}           what environment to provide to the container (optional) - equivalent of the ENV in Dockerfiles
-# entrypoint: []            what's the entrypoint of the image (optional)
-# command: []               what's the command of the image (optional)
-# ports: []                 what to EXPOSE
+# DESCRIPTION:
+# * name             Mandatory. The name of the rule
+# * srcs             Mandatory. The list of layers that compose the image
+# * description      Optional. The container description as it would be generated by docker
+# * image_labels     Optional. Embedded image labels
+# * environment      Optional. Same as doing ENV in a Dockerfile
+# * entrypoint       Optional. Same as ENTRYPOINT in a Dockerfile
+# * command          Optional. Same as CMD in a Dockerfile
+# * ports            Optional. Same as EXPOSE in a Dockerfile
+# * osversion        Optional (default = linux). 
+# * architecture     Optional (default = amd64).
+
 container_config(
-    name = 'ubuntu_new',
-    # baseimage = ":ubuntu_files_two",
+    name = 'ubuntu_config',
     srcs = [
         ":ubuntu_flat",
         ":ubuntu_files",
@@ -90,20 +98,26 @@ container_config(
         "443",
     ],
 )
-# CLOUDSDK_CONFIG has to point to the real $HOME/.config/gcloud directory, otherwise push will fail: please sets HOME to the current build dir
-# DOCKER_CONFIG has to point to a $HOME/.docker with configured docker credential/helper for gcr.io cases or some other auth completed already for private repos;
-# if the docker-credential-gcloud is being used, it has to be symlinked into the limited PATH used by please - either /usr/local/bin or /usr/bin
+
+# DESCRIPTION:
+# * name           Mandatory. The name of the rule; note that the rule will generate 2 separate rules, the one that does the push is called '${name}_push'; invoking just the name won't work
+# * srcs           Mandatory. The ORDERED list of layers that compose the image. Always start with the baseimage (if any), followed by smaller layers; the LAST one MUST be a previously defined "container_config" target.
+# * image_name     Optional. The name of the generated image; if absent, will use the ${name} field
+# * tag            Optional. Extra tag for the image. The rule uses by default 12 chars from the digest of the image and the $CI_COMMIT_TAG variable (if defined);
+# REQUIREMENTS:
+# * CLOUDSDK_CONFIG has to point to the real $HOME/.config/gcloud directory (by default), otherwise push will fail, since please sets $HOME to the current build dir
+# * DOCKER_CONFIG has to point to a $HOME/.docker with configured docker credentials/helpers for private repos use-case;
+# * any credential helper for docker has to be linked into /usr/local/bin or /usr/bin (e.g. docker-credential-gcloud)
 container_push(
     name = 'ubuntu_custom',
     srcs = [
         ":ubuntu_flat",
         ":ubuntu_files",
         ":ubuntu_files_two",
-        ":ubuntu_new",
+        ":ubuntu_config",
     ],
-    image_name = "foo",                    # optional, if you want image name to be different from the rule name
-    tag = "foobarv2",                        # optional, will use the image digest (default) an $CI_COMMIT_TAG if defined; this one will the the 3rd
-    # repository = "gcr.io/tcn-cloud-dev/m", # optional, will use CONFIG.DEFAULT_DOCKER_REPO as default;
+    image_name = "foo",
+    tag = "foobarv2",
 )
 
 container_make(