Adding data to SMTK

There are two tasks related to adding data to SMTK:

  1. Storing data in the SMTK repository; and

  2. Embedding data in SMTK libraries, plugins, and/or python modules.

Data in the repository

SMTK uses Git Large File Storage (LFS) to hold large files of any format, whether it be binary or ASCII. Using Git LFS is a way to reduce the amount of data developers must download to just that in active use by the branch of SMTK they are working on.

If you need to add a large file to SMTK,

  • Ask SMTK developers the best approach to hosting the data early in the process to avoid extra work.

  • If Git LFS is the proper way to add data, ensure that you have run git lfs install in your local SMTK clone and use git lfs status to verify that large files you are about to commit will be stored with LFS.

Embedding data in SMTK targets

SMTK provides a CMake macro, smtk_encode_file(), that will transcribe a repository file into a C++ literal, C++ function, or Python block-quote. This generated file can be built into targets such as libraries, plugins, or Python modules – allowing you to load content without needing to locate where on a user’s filesystem it might reside.

smtk_encode_file

This function adds a custom command that generates a C++ header or Python source-file which encodes the contents of a file (<xml>) from your source directory. This is used frequently for operation sim-builder template (SBT) files, icon (SVG) files, and other data you wish to include in packages. By encoding the file, there is no need to rely on code to search for it on the filesystem; it is either compiled into a library (C++) or included as part of a python module (which uses Python’s utilities for importing the data rather than requiring you to find it).

Because this function is frequently used to encode SMTK operation SBT files, it provides a utility to replace XML <include href="…"/> directives with the contents of the referenced file. Query paths for included files are passed to this macro with the flag INCLUDE_DIRS.

By default, the output header or python files are placed in the binary directory that corresponds to their source path, but with the input content type (e.g., _xml, _json, _svg) appended and the appropriate extension (.h or .py). If you wish to override this, pass an output filename to the DESTINATION option.

smtk_encode_file(
  <xml>
  INCLUDE_DIRS <path_to_include_directories>
  EXT "py" (optional: defaults to "h" and C++; use "py" for python)
  NAME "var" (optional: the name of the generated string literal or function)
  TYPE "_json" (optional: defaults to "_xml", appended to file and var name)
  HEADER_OUTPUT var (optional: filled in with full path of generated header)
  DESTINATION var (optional: specify output relative to current build dir)
)

Note that if you use smtk_encode_file() in a subdirectory relative to the target which compiles its output, you must add the DESTINATION (if specified) or the value returned in HEADER_OUTPUT to a custom_target (see this FAQ for details on why).

TARGET_OUTPUT can be used to generate a custom_target directly, but it is not recommended because it causes long paths and extra targets for make and VS projects on windows.

Note that if you are using smtk_encode_file external to SMTK, you do not need to include ${smtk_PREFIX_PATH}/${SMTK_OPERATION_INCLUDE_DIR} in INCLUDE_DIRS as it is automatically added; this allows your external projects to reference the operation, result, and hint attribute definitions that SMTK provides.

Currently, the following TYPE options are recognized: _py, _json, _svg, _xml, and _cpp. The cpp option does not indicate the input-file’s content format but rather that the output file should be an inline, anonymous-namespaced C++ function. This option exists for large files (more than 16kiB), for which MSVC compilers cannot produce a string-literal.