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