VTK  9.5.20250812
vtkEncodeString.cmake
Go to the documentation of this file.
1#[==[
2@file vtkEncodeString.cmake
3
4This module contains the @ref vtk_encode_string function which may be used to
5turn a file into a C string. This is primarily used within a program so that
6the content does not need to be retrieved from the filesystem at runtime, but
7can still be developed as a standalone file.
8#]==]
9
10set(_vtkEncodeString_script_file "${CMAKE_CURRENT_LIST_FILE}")
11
12#[==[
13@brief Encode a file as a C string at build time
14
15Adds a rule to turn a file into a C string. Note that any Unicode characters
16will not be replaced with escaping, so it is recommended to avoid their usage
17in the input.
18
19~~~
20vtk_encode_string(
21 INPUT <input>
22 [NAME <name>]
23 [EXPORT_SYMBOL <symbol>]
24 [EXPORT_HEADER <header>]
25 [HEADER_OUTPUT <variable>]
26 [SOURCE_OUTPUT <variable>]
27
28 [ABI_MANGLE_SYMBOL_BEGIN <being>]
29 [ABI_MANGLE_SYMBOL_END <end>]
30 [ABI_MANGLE_HEADER <header>]
31
32 [BINARY] [NUL_TERMINATE])
33~~~
34
35The only required variable is `INPUT`, however, it is likely that at least one
36of `HEADER_OUTPUT` or `SOURCE_OUTPUT` will be required to add them to a
37library.
38
39 * `INPUT`: (Required) The path to the file to be embedded. If a relative path
40 is given, it will be interpreted as being relative to
41 `CMAKE_CURRENT_SOURCE_DIR`.
42 * `NAME`: This is the base name of the files that will be generated as well
43 as the variable name for the C string. It defaults to the basename of the
44 input without extensions.
45 * `EXPORT_SYMBOL`: The symbol to use for exporting the variable. By default,
46 it will not be exported. If set, `EXPORT_HEADER` must also be set.
47 * `EXPORT_HEADER`: The header to include for providing the given export
48 symbol. If set, `EXPORT_SYMBOL` should also be set.
49 * `HEADER_OUTPUT`: The variable to store the generated header path.
50 * `SOURCE_OUTPUT`: The variable to store the generated source path.
51 * `BINARY`: If given, the data will be written as an array of `unsigned char`
52 bytes.
53 * `NUL_TERMINATE`: If given, the binary data will be `NUL`-terminated. Only
54 makes sense with the `BINARY` flag. This is intended to be used if
55 embedding a file as a C string exceeds compiler limits on string literals
56 in various compilers.
57 * `ABI_MANGLE_SYMBOL_BEGIN`: Open a mangling namespace with the given symbol.
58 If given, `ABI_MANGLE_SYMBOL_END` and `ABI_MANGLE_HEADER` must also be set.
59 * `ABI_MANGLE_SYMBOL_END`: Close a mangling namespace with the given symbol.
60 If given, `ABI_MANGLE_SYMBOL_BEGIN` and `ABI_MANGLE_HEADER` must also be set.
61 * `ABI_MANGLE_HEADER`: The header which provides the ABI mangling symbols.
62 If given, `ABI_MANGLE_SYMBOL_BEGIN` and `ABI_MANGLE_SYMBOL_END` must also
63 be set.
64#]==]
65function (vtk_encode_string)
66 cmake_parse_arguments(PARSE_ARGV 0 _vtk_encode_string
67 "BINARY;NUL_TERMINATE"
68 "INPUT;NAME;EXPORT_SYMBOL;EXPORT_HEADER;HEADER_OUTPUT;SOURCE_OUTPUT;ABI_MANGLE_SYMBOL_BEGIN;ABI_MANGLE_SYMBOL_END;ABI_MANGLE_HEADER"
69 "")
70
71 if (_vtk_encode_string_UNPARSED_ARGUMENTS)
72 message(FATAL_ERROR
73 "Unrecognized arguments to vtk_encode_string: "
74 "${_vtk_encode_string_UNPARSED_ARGUMENTS}")
75 endif ()
76
77 if (NOT DEFINED _vtk_encode_string_INPUT)
78 message(FATAL_ERROR
79 "Missing `INPUT` for vtk_encode_string.")
80 endif ()
81
82 if (NOT DEFINED _vtk_encode_string_NAME)
83 get_filename_component(_vtk_encode_string_NAME
84 "${_vtk_encode_string_INPUT}" NAME_WE)
85 endif ()
86
87 if (DEFINED _vtk_encode_string_EXPORT_SYMBOL AND
88 NOT DEFINED _vtk_encode_string_EXPORT_HEADER)
89 message(FATAL_ERROR
90 "Missing `EXPORT_HEADER` when using `EXPORT_SYMBOL`.")
91 endif ()
92
93 if (DEFINED _vtk_encode_string_EXPORT_HEADER AND
94 NOT DEFINED _vtk_encode_string_EXPORT_SYMBOL)
95 message(WARNING
96 "Missing `EXPORT_SYMBOL` when using `EXPORT_HEADER`.")
97 endif ()
98
99 if (DEFINED _vtk_encode_string_ABI_MANGLE_SYMBOL_BEGIN AND
100 (NOT DEFINED _vtk_encode_string_ABI_MANGLE_SYMBOL_END OR
101 NOT DEFINED _vtk_encode_string_ABI_MANGLE_HEADER))
102 message(WARNING
103 "Missing `ABI_MANGLE_SYMBOL_END` or `ABI_MANGLE_HEADER` when using "
104 "`ABI_MANGLE_SYMBOL_BEGIN`.")
105 endif ()
106
107 if (DEFINED _vtk_encode_string_ABI_MANGLE_SYMBOL_END AND
108 (NOT DEFINED _vtk_encode_string_ABI_MANGLE_SYMBOL_BEGIN OR
109 NOT DEFINED _vtk_encode_string_ABI_MANGLE_HEADER))
110 message(WARNING
111 "Missing `ABI_MANGLE_SYMBOL_BEGIN` or `ABI_MANGLE_HEADER` when using "
112 "`ABI_MANGLE_SYMBOL_END`.")
113 endif ()
114
115 if (DEFINED _vtk_encode_string_ABI_MANGLE_HEADER AND
116 (NOT DEFINED _vtk_encode_string_ABI_MANGLE_SYMBOL_BEGIN OR
117 NOT DEFINED _vtk_encode_string_ABI_MANGLE_SYMBOL_END))
118 message(WARNING
119 "Missing `ABI_MANGLE_SYMBOL_BEGIN` or `ABI_MANGLE_SYMBOL_END` when "
120 "using `ABI_MANGLE_HEADER`.")
121 endif ()
122
123 if (NOT _vtk_encode_string_BINARY AND _vtk_encode_string_NUL_TERMINATE)
124 message(FATAL_ERROR
125 "The `NUL_TERMINATE` flag only makes sense with the `BINARY` flag.")
126 endif ()
127
128 set(_vtk_encode_string_header
129 "${CMAKE_CURRENT_BINARY_DIR}/${_vtk_encode_string_NAME}.h")
130 set(_vtk_encode_string_source
131 "${CMAKE_CURRENT_BINARY_DIR}/${_vtk_encode_string_NAME}.cxx")
132
133 if (IS_ABSOLUTE "${_vtk_encode_string_INPUT}")
134 set(_vtk_encode_string_input
135 "${_vtk_encode_string_INPUT}")
136 else ()
137 set(_vtk_encode_string_input
138 "${CMAKE_CURRENT_SOURCE_DIR}/${_vtk_encode_string_INPUT}")
139 endif ()
140
141 set(_vtk_encode_string_depends_args)
142 if (CMAKE_VERSION VERSION_GREATER_EQUAL "3.27")
143 list(APPEND _vtk_encode_string_depends_args
144 DEPENDS_EXPLICIT_ONLY)
145 endif ()
146
147 add_custom_command(
148 OUTPUT ${_vtk_encode_string_header}
149 ${_vtk_encode_string_source}
150 DEPENDS "${_vtkEncodeString_script_file}"
151 "${_vtk_encode_string_input}"
152 COMMAND "${CMAKE_COMMAND}"
153 "-Dsource_dir=${CMAKE_CURRENT_SOURCE_DIR}"
154 "-Dbinary_dir=${CMAKE_CURRENT_BINARY_DIR}"
155 "-Dsource_file=${_vtk_encode_string_input}"
156 "-Doutput_name=${_vtk_encode_string_NAME}"
157 "-Dexport_symbol=${_vtk_encode_string_EXPORT_SYMBOL}"
158 "-Dexport_header=${_vtk_encode_string_EXPORT_HEADER}"
159 "-Dabi_mangle_symbol_begin=${_vtk_encode_string_ABI_MANGLE_SYMBOL_BEGIN}"
160 "-Dabi_mangle_symbol_end=${_vtk_encode_string_ABI_MANGLE_SYMBOL_END}"
161 "-Dabi_mangle_header=${_vtk_encode_string_ABI_MANGLE_HEADER}"
162 "-Dbinary=${_vtk_encode_string_BINARY}"
163 "-Dnul_terminate=${_vtk_encode_string_NUL_TERMINATE}"
164 "-D_vtk_encode_string_run=ON"
165 -P "${_vtkEncodeString_script_file}"
166 ${_vtk_encode_string_depends_args})
167
168 if (DEFINED _vtk_encode_string_SOURCE_OUTPUT)
169 set("${_vtk_encode_string_SOURCE_OUTPUT}"
170 "${_vtk_encode_string_source}"
171 PARENT_SCOPE)
172 endif ()
173
174 if (DEFINED _vtk_encode_string_HEADER_OUTPUT)
175 set("${_vtk_encode_string_HEADER_OUTPUT}"
176 "${_vtk_encode_string_header}"
177 PARENT_SCOPE)
178 endif ()
179endfunction ()
180
181if (_vtk_encode_string_run AND CMAKE_SCRIPT_MODE_FILE)
182 set(output_header "${binary_dir}/${output_name}.h")
183 set(output_source "${binary_dir}/${output_name}.cxx")
184
185 set(license_topfile "// SPDX-FileCopyrightText: Copyright (c) Ken Martin, Will Schroeder, Bill Lorensen\n// SPDX-License-Identifier: BSD-3-Clause\n")
186 file(WRITE "${output_header}" ${license_topfile})
187 file(WRITE "${output_source}" ${license_topfile})
188
189 file(APPEND "${output_header}"
190 "#ifndef ${output_name}_h\n#define ${output_name}_h\n\n")
191 if (export_header)
192 file(APPEND "${output_header}"
193 "#include \"${export_header}\"\n")
194 endif ()
195 if (abi_mangle_header AND abi_mangle_symbol_begin)
196 file(APPEND "${output_header}"
197 "#include \"${abi_mangle_header}\"\n\n${abi_mangle_symbol_begin}\n\n")
198 endif ()
199 if (export_symbol)
200 file(APPEND "${output_header}"
201 "${export_symbol} ")
202 endif ()
203
204 if (IS_ABSOLUTE "${source_file}")
205 set(source_file_full "${source_file}")
206 else ()
207 set(source_file_full "${source_dir}/${source_file}")
208 endif ()
209 set(hex_arg)
210 if (binary)
211 set(hex_arg HEX)
212 endif ()
213 file(READ "${source_file_full}" original_content ${hex_arg})
214
215 if (binary)
216 if (nul_terminate)
217 string(APPEND original_content "00")
218 endif ()
219 string(LENGTH "${original_content}" output_size)
220 math(EXPR output_size "${output_size} / 2")
221 file(APPEND "${output_header}"
222 "extern const unsigned char ${output_name}[${output_size}];\n\n")
223 if (abi_mangle_symbol_end)
224 file(APPEND "${output_header}"
225 "${abi_mangle_symbol_end}\n")
226 endif ()
227 file(APPEND "${output_header}"
228 "#endif\n")
229
230 file(APPEND "${output_source}"
231 "#include \"${output_name}.h\"\n\n")
232 if (abi_mangle_symbol_begin)
233 file(APPEND "${output_source}"
234 "${abi_mangle_symbol_begin}\n\n")
235 endif ()
236 file(APPEND "${output_source}"
237 "const unsigned char ${output_name}[${output_size}] = {\n")
238 string(REGEX REPLACE "\‍([0-9a-f][0-9a-f]\‍)" ",0x\\1" escaped_content "${original_content}")
239 # Hard line wrap the file.
240 string(REGEX REPLACE "\‍(..........................................................................,\‍)" "\\1\n" escaped_content "${escaped_content}")
241 # Remove the leading comma.
242 string(REGEX REPLACE "^," "" escaped_content "${escaped_content}")
243 file(APPEND "${output_source}"
244 "${escaped_content}\n")
245 file(APPEND "${output_source}"
246 "};\n")
247 if (abi_mangle_symbol_end)
248 file(APPEND "${output_source}"
249 "${abi_mangle_symbol_end}\n")
250 endif ()
251 else ()
252 file(APPEND "${output_header}"
253 "extern const char *${output_name};\n\n")
254 if (abi_mangle_symbol_end)
255 file(APPEND "${output_header}"
256 "${abi_mangle_symbol_end}\n\n")
257 endif ()
258 file(APPEND "${output_header}"
259 "#endif\n")
260
261 # Escape literal backslashes.
262 string(REPLACE "\\" "\\\\" escaped_content "${original_content}")
263 # Escape literal double quotes.
264 string(REPLACE "\"" "\\\"" escaped_content "${escaped_content}")
265 # Turn newlines into newlines in the C string.
266 string(REPLACE "\n" "\\n\"\n\"" escaped_content "${escaped_content}")
267
268 file(APPEND "${output_source}"
269 "#include \"${output_name}.h\"\n\n")
270 if (abi_mangle_symbol_begin)
271 file(APPEND "${output_source}"
272 "${abi_mangle_symbol_begin}\n\n")
273 endif ()
274 file(APPEND "${output_source}"
275 "const char *${output_name} =\n")
276 file(APPEND "${output_source}"
277 "\"${escaped_content}\";\n")
278 if (abi_mangle_symbol_end)
279 file(APPEND "${output_source}"
280 "\n${abi_mangle_symbol_end}\n")
281 endif ()
282 endif ()
283endif ()
if
if(abs(tt - 1.0)< eps)
Definition PyrC1Basis.h:1
vtkHDFUtilities::Open
VTKIOHDF_EXPORT bool Open(const char *fileName, hid_t &fileID)
Open a VTK HDF file and checks if it is valid.
vtkX3D::on
@ on
Definition vtkX3D.h:439
vtkX3D::function
@ function
Definition vtkX3D.h:249
vtkX3D::time
@ time
Definition vtkX3D.h:497
vtkX3D::content
@ content
Definition vtkX3D.h:302
vtkX3D::name
@ name
Definition vtkX3D.h:219
vtkX3D::data
@ data
Definition vtkX3D.h:315
vtkX3D::string
@ string
Definition vtkX3D.h:490
source
boost::graph_traits< vtkGraph * >::vertex_descriptor source(boost::graph_traits< vtkGraph * >::edge_descriptor e, vtkGraph *)
Definition vtkBoostGraphAdapter.h:984
vtk_encode_string
function vtk_encode_string()
Encode a file as a C string at build time.
Definition vtkEncodeString.cmake:65
Generated on Tue Aug 12 2025 12:27:20 for VTK by doxygen 1.9.7