Cross package maker. DEB/RPM generation or conversion. Derived from jordansissel/fpm.

⌈⌋ ⎇ branch:  cross package maker


Artifact [9767c7a3e9]

Artifact 9767c7a3e9b8c3c4a2cb45320a89666059fec819:

Wiki page [src] by mario 2015-01-28 12:33:57.
D 2015-01-28T12:33:57.701
L src
N text/x-markdown
P d48580cceb02ab33a1c5b688d490c3f1244adc82
U mario
W 4417
## <kbd>*-s* `src`</kbd> input plugin

The "`src`" module allows packaging scripting language apps through **self-referencing** *package infos*.

It extracts package information from the first given input file. It looks for a top-level comment block with `key: value` fields. It's language-agnostic and understands coherent `#` lines or `//` comments and multiline `/*...*/` blocks.

    # title: FooBar
    # description: does the stuff
    # version: 0.2
    # architecture: all
    # license: BSDL
    # pack: lib/dependency.py, ext/*.py, doc/README
    # 
    # Remainder of documentation block
    # is used as long description ...

Field names almost literally map to fpm packaging options. Command line flags (--description, --version, etc.) still can override extracted meta fields. Extra fields may be utilized by specific target plugins (`-t phar` does).


### Recursive `pack:` specifier

The <kbd>src</kbd> plugin mainly cares about the <b>`# pack:`</b> list, which references other file/script names to include.

 * Simple *comma-separated* file lists:

    * It can just enumerate `file1, file2, file3.py` plain files.

    * Or list files in subdirs `lib/file4, ../also.txt`

 * Similar to the <kbd>dir</kbd> source, it may also rename files:

    * With `src=dest, file5=file6.txt`

    * Or move them into target subdirectories `file7=lib/file7`  
      (The target directory directory can be an absolute path, if the fpm <kbd>--prefix</kbd> flag isn't used.)

 * Use glob patterns:

    * Where `*.py, *.txt` includes matching files from the current directory.

    * And `lib/*.py` recurses into a subdirectory.

    * Remap directory contents with `lib/*.sh=/opt/app/lib/shell/`

 * **Recursion**: Each referenced script file is scanned for <tt>pack:</tt> specifiers of its own.

    * For example, let the main script reference `lib/submodule.py`. Then all file references in the <tt>pack:</tt> line of `submodule.py` are treated as basenames within the `lib/` source directory.

    * This allows for simple file-to-file dependency chains / grouping. And submodules don't have to care themselves about their source residence, but only need to know neighboring/relative scripts.

 * Files can even exclude themselves from packaging with `pack: myself.py=`


It's actually rather simple in practice, and self-explanatory for each file. But see also [src.rb](artifact/fecac2e5d) for a more concise summary of how file relations are handled.



### Use cases

For small projects a single `pack:` specifier in the main script/file often suffices. It just lists files to be included and general package description fields. Which then allows terse invocations like:

    fpm -s src -t deb,rpm  main.sh

It's getting more interesting for modularized packages:

   * Main source file `st2.py`

         # pack: st2.py=bin/streamtuner2,
         #       channels/__init__.py=share/streamtuner2/channels/

   * And `channels/__init__.py` referencing the desired submodules

         # pack: a*, m*, y*, z*.png

From an actual example, which in reality isn't actually doing that. (Currently just packaging `*.*` all modules therein.)


### Notes

The meta format is losely based on [Generic PHP Plugins](http://milki.include-once.org/genericplugins/) and also recognized by the [<b>version</b>num copying tool](http://fossil.include-once.org/versionnum/). It's not yet formalized, but was very much designed with cross-language compatibility in mind.

For FPM/XPM the inset script basename also becomes the package name in absence of an `id:` field.

The remainder of the comment (after the meta fields) will substitute as long `--description` field.

So basically this scheme provides a file-embedded `.fpm` option and `--inputs` specification scheme; with just more generalized field names.

It could also be utilized for packaging binary apps. Simply craft a `spec.txt` file with `#` comment markers and key:value fields. The spec file can exclude itself with `# pack: spec.txt=, bin/*` for example.

With <kbd>--src-only</kbd> recursive pack: line lookups are disabled. Only the `pack:` list from the primary input file is acted on then.

 * fpm issue: [#811](https://github.com/jordansissel/fpm/issues/811)
 * orig gist: [fpm…package…**src.rb**](https://gist.github.com/prof-milki/7fac35d5737816e5a245)


Z a6f4e29d1cc4b8edba6ee742f52f48df