diff --git a/README.md b/README.md index 4dc6028..1ca1a02 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,37 @@ Instead of manually tweaking 100 artboards, you define reusable components once - **Unlimited Customization**: A user-defined recipe is actually a Python script that utilizes Assemblicon. Any form of composition can be achieved, which is what gives unlimited customization ability. - **Selective Build**: Only compile specific icons from the entire defined icon set. This provides a resource-saving way to check the built icons. +## Usage + +Assemblicon is a **library**, not a standalone application. It does not embed or ship any concrete icon set on its own. To do real work, an external project must depend on this library and drive it from its own recipe/script, then reuse the produced artifacts in its own build or distribution flow. + +The library is organized into two layers, which can be adopted independently: + +- **High level**: A ready-made, opinionated pipeline that assembles a conventional icon set with minimal code. Starting from common source kinds (bitmap, SVG, Blender, etc.) and intermediate artifacts, it derives and writes the standard output families (FreeDesktop, Windows, macOS) in one pass. Reach for this layer when you simply want a standard icon set as quickly as possible. +- **Low level**: A set of primitive, unopinionated building blocks covering the operations that icon assembly is actually made of (artifact input/output, rendering, temporary layout and composition). By wrapping these blocks with your own code, you can fully reuse the existing implementation while defining a custom icon set format and pipeline that is unique to your project. + +In short: use the high level to get a standard icon set fast, and the low level plus a thin custom wrapper when you need a format of your own. + +## CLI and Environment Variables + +The library ships a default CLI front-end that is meant to be a convenient starting point. It exposes the standard options below: + +- Input directory. +- Output directory. +- SVG renderer selection. +- **`--only`** (short `-l`): restrict the build to the jobs whose names are given. It accepts one or more names and may be repeated. Jobs that the selected ones depend on are still built as needed, so it is a resource-saving way to rebuild or verify only a subset of an entire icon set. + +Because Assemblicon is a library, this CLI is not fixed. You can write your own entry point and extend (or replace) the standard argument parser with project-specific options. + +The library also recognizes the following environment variables: + +| Variable | Purpose | +| --- | --- | +| `ASSEMBLICON_INKSCAPE` | Path or command name of the Inkscape executable used when rendering SVG through the Inkscape backend. Defaults to `inkscape`. | +| `ASSEMBLICON_RESVG` | Path or command name of the resvg executable used when rendering SVG through the resvg backend. Defaults to `resvg`. | +| `ASSEMBLICON_BLENDER` | Path or command name of the Blender executable used to render Blender compositions. Defaults to `blender`. | +| `ASSEMBLICON_LINK_MODE` | How an artifact is made reachable at another path: `symlink` (default) or `copy`. Set it to `copy` when symlinks are unavailable or undesirable, for example on Windows without the required privileges. | + ## License This project is licensed under the MIT License.