Allow a package to specify which files to include when creating a BALA file

[sameerajayasoma]

Each module in a package can optionally have a resources directory, and it can contain resource files other than source files required at the runtime. As per the current design, bal build packages such resources file files with the final executable, also bal pack packages them with the BALA file.

We've also come across requirements where developers need to include other kinds of resources with BALA files. Here are some examples:

• Icon files (Ballerina central shows an icon in the package display, it one exists)
• Additional files linked with the package and module documents (Package.md, Module.md)

We've also noticed that developers are maintaining these files in the resources directory of the default module. Such files will end up in the executable jar unintentionally.

[sameerajayasoma]

Here is how Rust handles this use case: https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields

[sameerajayasoma]

We could introduce a new field called includes to the [package] table in Ballerina.toml. This includes can contain a list of file patterns and we can include all the matching files to the BALA file.

[gayaldassanayake]

Where in the BALA should we include all the files that match the pattern given in includes field? How do we organise the files (that match the includes patterns) from different modules? Should we have a directory for each module and its file resources within that?

[gayaldassanayake]

With https://github.com/ballerina-platform/ballerina-lang/pull/36877 we support the use of patterns for the include field.

The pattern convention is based on,

1. gitignore documentation
2. Rust manifest include/exclude documentation

Patterns should use forward slashes as the separators following the unix convention.

Following are the supported patterns.

include = [
    "foo", # any file/dir with name 'foo'
    "/bar", # any file/dir with name 'bar' in the root dir of the package
    "baz/", # directories with name 'baz' (files are ignored)
    "/qux/", # any dir with name qux in the root dir
    "*.html", # any file with the extention .html
    "foo*bar.*", # any file that has a name in starting with 'foo', 
                 # ending with 'bar', 
                 # with any no of characters in the middle, 
                 # ending with an extension after a dot.
    "plug?", # any file/dir with name `plug` followed by a single character
                # eg:- 'plugr', 'plugz'
    "thud[ab]", # any file/dir with names 'thuda', 'thudb'
    "fred[q-s]", # any file/dir with names 'fredq' to 'thuds' in alphabetical order
    "**/grault/garply", # a file/dir that has '/grault/garply' at the end of their paths
    "waldo/xyzzy/**", # a file/dir that has waldo/xyzzy/' at the beginning,
                      # followed by the rest of the path
    "babble/**/bar", # a path that has 'babble', followed by any path in the middle,
                     # ending with 'bar'
    "*.rs", # files that has the extension '.rs'
    "!corge.rs", # exclude file 'corge.rs' from the selected paths of patterns above 
    "include-resources/thud", # direct dir path from the root is acceptable
    "include-resources/x.js", # direct file path from the root is acceptable
    ]