Adding data to SMTK¶
There are two tasks related to adding data to SMTK:
Storing data in the SMTK repository; and
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 usegit 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.