Usage in Qbs¶

Exporting assets and metadata¶

Using `SketchExport` product¶

The easiest way to start exporting your Sketch designs in Qbs is to use the provided by me item SketchExport.

import qbs

SketchExport {
    name: 'sketch-assets'
    files: '*.sketch'
}

This will automatically export everything that is marked as exportable in your Sketch documents (layers mode) + the metadata.

Using custom product¶

If you want to have more fine-grained control over the pipeline, you might decide to create a custom product.

Qbs won't build anything you haven't asked for. So if you want it to generate something from you sketch-files, you need to tell it that you need a certain type of artifacts. For that, you either need an active rule that waits for that type of artifacts as input or (a much simpler option) you can add corresponding file tags to your product type. Let's proceed with the latter option. Here is a sample check-list for you:

Add file tags as output types of your product
- sketch.export for exporting assets
- sketch.metadata for extracting metadata
```
Product {
    type: ['sketch.export', 'sketch.metadata']
}
```
Add dependencies
- Sketch.export for exporting assets
- Sketch.metadata for extracting metadata
- If you want to have a full control over what you are exporting, you can also use the following auxiliary modules:
Choose the exporting mode.

Difference to SketchExport

Well, there is no difference. Essentially this is exactly what SketchExport does:

import qbs

Product {
    Depends {
        name: 'Sketch'
        submodules: [
            'artboards',
            'export',
            'layers',
            'metadata',
            'pages',
            'preview',
        ]
    }
    Sketch.export.mode: 'layers'
    type: ['sketch.export', 'sketch.metadata']
}

However, if your product generates also other types of artifacts, it still may be beneficial to control everything manually.

Installing generated files¶

Assets¶

Sketch.export marks all the generated files with sketch.export tag. Additionally, every file gets a tag accordingly to its file-type (determined by extension). These could be: png, jpg, tiff, webp, pdf, eps, svg.

So, in order to install all these files, you need a Group with qbs.install:true. The Group will allow to skip the generated metadata from installation while the qbs.install property will tell Qbs to copy all files to your installation folder with planar structure (potentially overwriting the files with the same names from different folders).

If you want to keep the folder structure though, you can use qbs.installSourceBase as below:

import qbs

SketchExport {
    name: 'sketch-assets'
    files: '*.sketch'

    Group {
        fileTagsFilter: ['sketch.export']
        qbs.install: true

        // to keep the folder structure:
        qbs.installSourceBase: Sketch['export'].workingDir
    }
}

Sketch.export vs. Sketch['export']

Note that if you want to attach some module properties to your product, you can use the following syntax:

SketchExport {
    Sketch.export.formats: ['png', 'svg']
}

However, in the example above, it was clearly seen that I used it differently:

SketchExport {
    qbs.installSourceBase: Sketch['export'].workingDir
}

Although in JavaScript and QML (and thus in Qbs that inherits their syntax) there is no difference between those two variants, the following will trigger the error:

SketchExport {
    qbs.installSourceBase: Sketch.export.workingDir  // ⇒ SyntaxError: Parse error
}

That happens because export is a reserved word in JavaScript. If it is met in Qbs context (on the left side of a property assignment), there is no problem, but when the parser encounters it in JavaScript context (on the rigth side of a property assignment), it fails.

Since installing files as above is a quite common case, the module provides an additional item SketchExportGroup for your convenience. With it, the code becomes even shorter:

import qbs

SketchExport {
    name: 'sketch-assets'
    files: '*.sketch'

    SketchExportGroup {}  // installs everything preserving the folder structure
}