Blender V5.3
blender_project_config.cc
Go to the documentation of this file.
1/* SPDX-FileCopyrightText: 2026 Blender Authors
2 *
3 * SPDX-License-Identifier: GPL-2.0-or-later */
4
8
9#include <toml.hpp>
10
11#include "CLG_log.h"
12
13#include "BLI_fileops.hh"
14#include "BLI_listbase.hh"
15#include "BLI_path_utils.hh"
16#include "BLI_string.hh"
17#include "BLI_string_ref.hh"
18#include "BLI_uuid.hh"
19
21#include "BKE_global.hh"
22#include "BKE_preferences.h"
23
24#include "DNA_asset_types.h"
25#include "DNA_userdef_types.h"
26
27#include "RNA_access.hh"
28#include "RNA_define.hh"
29#include "RNA_enum_types.hh"
30#include "RNA_prototypes.hh"
31
32namespace blender {
33
34static CLG_LogRef LOG = {"project"};
35
36namespace bke {
37constexpr toml::spec toml_version = toml::spec::v(1, 0, 0);
38/* The schema version of the Project Config, for managing breaking schema changes.
39 *
40 * Only increment this when there are breaking schema changes.
41 *
42 * Project versioning should generally follow the same approach as blend file
43 * versioning. In short:
44 *
45 * - When reasonably possible, change the schema in ways that fully preserve
46 * backwards compatibility and that avoid critical forwards compatibility
47 * breaks.
48 * - When that's not possible, plan ahead and only make the needed breaking
49 * changes on major version bumps of Blender (e.g. 5.x -> 6.x).
50 * - In the version just before a major version bump, add forwards compatibility
51 * code for the anticipated breaking changes, so that e.g. the last 5.x release
52 * can still open projects from Blender 6.0.
53 *
54 * For more details, see:
55 * https://developer.blender.org/docs/handbook/guidelines/compatibility_handling_for_blend_files/
56 *
57 * NOTE: when incrementing this version number, ensure that the versioning code
58 * in `create_blender_project_from_toml()` is appropriately expanded to auto-upgrade
59 * between versions
60 */
62
63static std::string toml_type_name(const toml::value &value)
64{
65 switch (value.type()) {
66 case toml::value_t::empty:
67 return "empty";
68 case toml::value_t::boolean:
69 return "boolean";
70 case toml::value_t::integer:
71 return "integer";
72 case toml::value_t::floating:
73 return "float";
74 case toml::value_t::string:
75 return "string";
76 case toml::value_t::offset_datetime:
77 return "offset datetime";
78 case toml::value_t::local_datetime:
79 return "local datetime";
80 case toml::value_t::local_date:
81 return "local date";
82 case toml::value_t::local_time:
83 return "local time";
84 case toml::value_t::array:
85 return "array";
86 case toml::value_t::table:
87 return "table";
88 }
89
90 return "unknown";
91}
92
94 std::string name;
96 toml::value value;
98 std::string description;
99
100 void from_toml(const toml::value &v)
101 {
102 this->name = toml::find<std::string>(v, "name");
103 if (!is_valid_project_variable_name(this->name)) {
104 toml::value var = v.at("name");
105 std::string err = toml::format_error(
106 "Invalid project variable name",
107 var,
108 "Invalid variable name: \"" + this->name +
109 "\". Variable names can not be empty, must not start with a digit, and "
110 "must contain only alphanumeric characters and underscores.");
111
112 throw toml::type_error(err, var.location());
113 }
114
115 auto type = toml::find<std::string>(v, "type");
116 if (type == "INTEGER") {
117 this->type = ProjectVariableType::INT;
118 }
119 else if (type == "FLOAT") {
120 this->type = ProjectVariableType::FLOAT;
121 }
122 else if (type == "STRING") {
123 this->type = ProjectVariableType::STRING;
124 }
125 else {
126 toml::value var = v.at("type");
127 std::string err = toml::format_error(
128 "Invalid Project variable type",
129 var,
130 "invalid value for \'type' expected \"INTEGER\", \"FLOAT\", or \"STRING\", but got \"" +
131 type + "\"");
132
133 throw toml::type_error(err, var.location());
134 }
135
136 this->value = v.at("value");
137 toml::value value = this->value;
138
139 if (this->type == ProjectVariableType::INT && !value.is_integer()) {
140 std::string err = toml::format_error(
141 "Project Variable type and value mismatch",
142 value,
143 "Actual and declared type of project variable \"value\" do not match. Got \"" +
144 toml_type_name(value) + "\", expected an integer");
145
146 throw toml::type_error(err, value.location());
147 }
148 if (this->type == ProjectVariableType::FLOAT && !value.is_floating()) {
149 std::string err = toml::format_error(
150 "Project Variable type and value mismatch",
151 value,
152 "Actual and declared type of project variable \"value\" do not match. Got \"" +
153 toml_type_name(value) + "\", expected a float");
154
155 throw toml::type_error(err, value.location());
156 }
157 if (this->type == ProjectVariableType::STRING) {
158 if (!value.is_string()) {
159 std::string err = toml::format_error(
160 "Project Variable type and value mismatch",
161 value,
162 "Actual and declared type of project variable \"value\" do not match. Got \"" +
163 toml_type_name(value) + "\", expected a string");
164
165 throw toml::type_error(err, value.location());
166 }
167
168 auto subtype = toml::find<std::string>(v, "subtype");
169
170 if (subtype == "NONE") {
172 }
173 else if (subtype == "FILEPATH") {
175 }
176 else {
177 toml::value var = v.at("subtype");
178 std::string err = toml::format_error("Invalid Project variable subtype",
179 var,
180 "invalid value for \'subtype' expected \"NONE\" or "
181 "\"FILEPATH\", but got \"" +
182 subtype + "\"");
183
184 throw toml::type_error(err, var.location());
185 }
186 }
187 this->description = toml::find_or(v, "description", "");
188 }
189};
190
192{
193 ProjectVariable *new_var = project->new_variable(project_variable.name, project_variable.type);
194 toml::value value = project_variable.value;
195
196 switch (project_variable.type) {
198 new_var->value_set(toml::get<int>(value));
199 break;
201 new_var->value_set(toml::get<float>(value));
202 break;
204 new_var->value_set(toml::get<std::string>(value));
205 new_var->string_subtype_set(project_variable.subtype);
206 break;
207 default:
209 break;
210 }
211
212 if (project_variable.description != "") {
213 new_var->description_set(project_variable.description);
214 }
215}
216
218 /* Common variables. */
219 std::string name;
220 int import_method; /* eAssetImportMethod enum */
221 /* Remote library variables. */
223 false; /* Only used to keep track if "url" was defined when parsing. */
224 std::string url;
225 std::string access_token;
226 /* Local library variables. */
227 std::string path;
229 std::string uuid;
230
231 void from_toml(const toml::value &v)
232 {
233 this->name = toml::find<std::string>(v, "name");
234
235 std::string import_method_str = toml::find<std::string>(v, "import_method");
237 rna_enum_asset_import_method_items, import_method_str.c_str(), &this->import_method))
238 {
239 toml::value var = v.at("import_method");
240 std::string err = toml::format_error("Invalid Project asset library import method",
241 var,
242 "invalid value for \'import_method. "
243 "\"" +
244 import_method_str +
245 "\" is not a valid import method");
246
247 throw toml::type_error(err, var.location());
248 }
249
250 if (v.contains("url")) {
251 this->is_remote_asset_lib = true;
252 this->url = toml::find<std::string>(v, "url");
253
254 this->access_token = toml::find_or(v, "access_token", "");
255 return;
256 }
257
258 this->path = toml::find<std::string>(v, "path");
259
260 this->use_relative_path = toml::find<bool>(v, "use_relative_path");
261
262 this->uuid = toml::find_or(v, "uuid", "");
263 }
264};
265
266static void project_asset_library_add(TomlAssetLibrary project_asset_library)
267{
268 if (project_asset_library.is_remote_asset_lib) {
270 &U,
271 project_asset_library.name.c_str(),
272 project_asset_library.url.c_str(),
273 project_asset_library.access_token.c_str());
274
275 new_library->import_method = project_asset_library.import_method;
276 return;
277 }
278
279 std::optional<UUID> uuid = {};
280 bool invalid_uuid = false;
281 if (project_asset_library.uuid != "") {
282 try {
283 uuid = UUID(project_asset_library.uuid);
284 }
285 catch (const std::runtime_error &e) {
286 invalid_uuid = true;
287 }
288 }
289
291 &U, project_asset_library.name.c_str(), project_asset_library.path.c_str(), uuid);
292
293 if (invalid_uuid) {
294 /* User passed an invalid UUID, disable the library and set the invalid_uuid string so we can
295 * notify the user about this in the UI.
296 */
297 new_library->flag |= ASSET_LIBRARY_DISABLED;
298 new_library->invalid_uuid = BLI_strdup(project_asset_library.uuid.c_str());
299 }
300
301 if (project_asset_library.use_relative_path) {
302 new_library->flag |= ASSET_LIBRARY_RELATIVE_PATH;
303 }
304 new_library->import_method = project_asset_library.import_method;
305}
306
308 std::string toml_path,
309 std::string project_root_path)
310{
311 /* This blender::fstream is needed to properly handle utf-8 paths on Windows. */
312 blender::fstream config_file(toml_path, std::ios::in | std::ios::binary);
313 if (!config_file.is_open()) {
314 throw std::system_error(errno, std::generic_category(), "Failed to open file: " + toml_path);
315 }
316
317 toml::value config_values = toml::parse(config_file, toml_path, toml_version);
318 toml::value schema_var = config_values.at("schema_version");
319 int version = schema_var.as_integer();
320
321 if (version > project_schema_version) {
322 std::string err = toml::format_error(
323 "Too new project schema version!",
324 schema_var,
325 "expected a value equal or below: " + std::to_string(project_schema_version) + "\"");
326 throw toml::type_error(err, schema_var.location());
327 }
328
329 if (version < project_schema_version) {
330 // Versioning code here
331 }
332
333 auto project_name = toml::find<std::string>(config_values, "name");
334 if (!BKE_blender_project_init(project_name, project_root_path)) {
335 throw std::invalid_argument(
336 "Couldn't initialize the project because the project name was empty");
337 }
339
340 if (config_values.contains("ocio_config")) {
341 auto ocio_config_path = config_values.at("ocio_config").as_string();
342 project->set_ocio_config_path(ocio_config_path);
343 }
344
345 if (config_values.contains("variables")) {
346 for (const auto &variable : toml::find<toml::array>(config_values, "variables")) {
347 auto project_variable = toml::get<TomlProjectVariable>(variable);
348 project_variable_add(project, project_variable);
349 }
350 }
351
352 if (config_values.contains("asset_libraries")) {
353 for (const auto &library : toml::find<toml::array>(config_values, "asset_libraries")) {
354 auto project_asset_library = toml::get<TomlAssetLibrary>(library);
355 project_asset_library_add(project_asset_library);
356 }
357 }
358
359 if (config_values.contains("splash_image")) {
360 auto splash_image_path = config_values.at("splash_image").as_string();
361 project->set_splash_image_path(splash_image_path);
362 }
363
364 // TODO: check if we didn't access any of the parsed toml variables
365 // We need to build the toml lib with "TOML11_ENABLE_ACCESS_CHECK" to do this though.
366
367 /* Done loading, mark project as non dirty. */
368 project->is_dirty = false;
369}
370
372{
373 toml::ordered_array toml_array;
374 for (auto &project_variable : project->variables) {
375 toml::ordered_table variable_data = {{"name", std::string(project_variable->name_get())}};
376
377 ProjectVariableType type = project_variable->type_get();
378 ProjectVariableStringSubtype string_subtype;
379
380 const char *idname;
381 if (RNA_enum_id_from_value(rna_enum_project_variable_type_items, int(type), &idname) == 0) {
382 /* This lookup should never fail. */
384 }
385 variable_data["type"] = std::string(idname);
386
387 switch (project_variable->type_get()) {
389 variable_data["value"] = project_variable->value_int_get();
390 break;
392 variable_data["value"] = project_variable->value_float_get();
393 break;
395 variable_data["value"] = std::string(project_variable->value_string_get());
396 string_subtype = project_variable->string_subtype_get();
398 rna_enum_project_variable_string_subtype_items, int(string_subtype), &idname) == 0)
399 {
400 /* This lookup should never fail. */
402 }
403 variable_data["subtype"] = std::string(idname);
404 break;
405 default:
407 break;
408 }
409
410 StringRefNull description = project_variable->description_get();
411
412 if (!description.is_empty()) {
413 variable_data["description"] = std::string(description);
414 }
415
416 toml_array.push_back(variable_data);
417 }
418 return toml_array;
419}
420
421static toml::ordered_array project_asset_libraries_to_toml()
422{
423 toml::ordered_array toml_array;
424 for (auto &user_library : U.asset_libraries.items_mutable()) {
425 if ((user_library.flag & ASSET_LIBRARY_PROJECT_DEFINED)) {
426 const char *import_method;
428 int(user_library.import_method),
429 &import_method) == 0)
430 {
431 /* This lookup should never fail. */
433 }
434 toml::ordered_table asset_library_data;
435 if (user_library.flag & ASSET_LIBRARY_USE_REMOTE_URL) {
436 /* remote asset library */
437 asset_library_data = {{"name", user_library.name},
438 {"import_method", std::string(import_method)},
439 {"url", user_library.remote_url}};
440 if (user_library.flag & ASSET_LIBRARY_USE_AUTH_TOKEN && user_library.auth_token) {
441 asset_library_data["access_token"] = std::string(user_library.auth_token);
442 }
443 }
444 else {
445 /* Local asset library */
446 UUID uuid = UUID(user_library.uuid);
447 asset_library_data = {
448 {"name", user_library.name},
449 {"import_method", std::string(import_method)},
450 {"path", user_library.dirpath},
451 {"use_relative_path", bool(user_library.flag & ASSET_LIBRARY_RELATIVE_PATH)},
452 {"uuid", uuid.str()}};
453 }
454 toml_array.push_back(asset_library_data);
455 }
456 }
457 return toml_array;
458}
459
461{
462 toml::ordered_table toml_table = {{"schema_version", project_schema_version},
463 {"name", std::string(project->get_name())}};
464
465 StringRefNull ocio_config_path = project->get_ocio_config_path();
466 if (!ocio_config_path.is_empty()) {
467 toml_table["ocio_config"] = std::string(ocio_config_path);
468 }
469
470 toml::ordered_array variables = project_variables_to_toml(project);
471 if (!variables.empty()) {
472 toml_table["variables"] = variables;
473 }
474
475 toml::ordered_array asset_libraries = project_asset_libraries_to_toml();
476 if (!asset_libraries.empty()) {
477 toml_table["asset_libraries"] = asset_libraries;
478 }
479
480 StringRefNull splash_image_path = project->get_splash_image_path();
481 if (!splash_image_path.is_empty()) {
482 toml_table["splash_image"] = std::string(splash_image_path);
483 }
484
485 return toml_table;
486}
487
488} // namespace bke
489
491{
492 if (!(U.pref_flag & USER_PREF_FLAG_PROJECT_SAVE)) {
493 return;
494 }
495 const bool is_dirty = BKE_blender_project_read_callback(
496 bmain, [](const bke::BlenderProject *project) { return project && project->is_dirty; });
497 if (is_dirty) {
499 }
500}
501
503{
505 if (project == nullptr) {
506 CLOG_ERROR(&LOG, "Couldn't save project config, no active project.");
507 return false;
508 }
509 /* Create the directory for new projects. */
510 const std::string config_dir = project->get_root_path() + SEP_STR + BLENDER_PROJECT_CONFIG_DIR;
511 if (!BLI_dir_create_recursive(config_dir.c_str())) {
512 CLOG_ERROR(&LOG, "Failed to create project config directory '%s'", config_dir.c_str());
513 return false;
514 }
515
516 std::string toml_path = config_dir + SEP_STR + BLENDER_PROJECT_CONFIG_FILE;
517
518 toml::ordered_table toml_config = create_toml_from_blender_project(project);
519
520 /* This blender::fstream is needed to properly handle utf-8 paths on Windows. */
521 blender::fstream config_file(toml_path, std::ios::out | std::ios::binary);
522 if (!config_file.is_open()) {
524 "Failed to open project config file '%s' for writing: %s",
525 toml_path.c_str(),
526 std::strerror(errno));
527 return false;
528 }
529 config_file << toml::format(toml::ordered_value(toml_config), bke::toml_version);
530 config_file.close(); /* Flush to get all failures. */
531 if (config_file.fail()) {
532 return false;
533 }
534
535 project->is_dirty = false;
536
537 if (!G.background) {
538 /* Update the recent projects in case the project name changed (or if this is a new project).
539 */
541 }
542
543 return true;
544}
545
546bool BKE_blender_project_init_from_root_path(Main *bmain, std::string project_root_path)
547{
548 if (!BLI_is_dir(project_root_path.c_str())) {
549 CLOG_ERROR(&LOG, "Project root path '%s', is not a directory", project_root_path.c_str());
550 return false;
551 }
552 std::string toml_path = project_root_path + SEP_STR + BLENDER_PROJECT_CONFIG_DIR + SEP_STR +
554 if (!BLI_is_file(toml_path.c_str())) {
555 CLOG_ERROR(&LOG, "Project has no project.toml file");
556 return false;
557 }
558
559 try {
560 bke::create_blender_project_from_toml(bmain, toml_path, project_root_path);
561 }
562 catch (const std::exception &e) {
563 CLOG_ERROR(&LOG, "Failed loading project from toml: \n%s", e.what());
564 /* Delete any project and its data if managed to create one before failing with an error. */
566 return false;
567 }
568 CLOG_INFO_NOCHECK(&LOG, "Open project: \"%s\"", project_root_path.c_str());
569 return true;
570}
571
572} // namespace blender
#define BLENDER_PROJECT_CONFIG_DIR
#define BLENDER_PROJECT_CONFIG_FILE
File and directory operations.
#define CLOG_ERROR(clg_ref,...)
Definition CLG_log.h:188
#define CLOG_INFO_NOCHECK(clg_ref, format,...)
Definition CLG_log.h:204
#define BLI_assert_unreachable()
UUID()=default
std::string str() const
Definition uuid.cc:162
void string_subtype_set(ProjectVariableStringSubtype type)
void description_set(StringRef description)
void value_set(StringRefNull value)
constexpr bool is_empty() const
constexpr toml::spec toml_version
static toml::ordered_table create_toml_from_blender_project(BlenderProject *project)
static toml::ordered_array project_asset_libraries_to_toml()
static void project_variable_add(BlenderProject *project, TomlProjectVariable project_variable)
static void create_blender_project_from_toml(Main *bmain, std::string toml_path, std::string project_root_path)
static toml::ordered_array project_variables_to_toml(BlenderProject *project)
static void project_asset_library_add(TomlAssetLibrary project_asset_library)
const int project_schema_version
static std::string toml_type_name(const toml::value &value)
bool is_valid_project_variable_name(StringRef name)
BMesh Iterators.
UserDef U
Definition blender.cc:58
const EnumPropertyItem rna_enum_asset_import_method_items[]
Definition rna_asset.cc:54
void BKE_blender_project_config_autosave(Main *bmain)
@ ASSET_LIBRARY_USE_AUTH_TOKEN
@ ASSET_LIBRARY_PROJECT_DEFINED
@ ASSET_LIBRARY_DISABLED
@ ASSET_LIBRARY_USE_REMOTE_URL
@ ASSET_LIBRARY_RELATIVE_PATH
bool BLI_dir_create_recursive(const char *dirname) ATTR_NONNULL()
Definition fileops_c.cc:416
bke::BlenderProject * BKE_blender_project_get(const Main *bmain)
const EnumPropertyItem rna_enum_project_variable_type_items[]
ATTR_WARN_UNUSED_RESULT const BMVert * v
auto BKE_blender_project_read_callback(const Main *bmain, Fn lambda)
void BKE_blender_project_clear()
Global G
Definition blender.cc:57
struct bUserAssetLibrary * BKE_preferences_project_asset_library_add(struct UserDef *userdef, const char *name, const char *dirpath, std::optional< UUID > uuid=std::nullopt) ATTR_NONNULL(1)
@ USER_PREF_FLAG_PROJECT_SAVE
void BKE_blender_project_recent_update(const Main *bmain)
struct bUserAssetLibrary bUserAssetLibrary * BKE_preferences_project_remote_asset_library_add(UserDef *userdef, const char *name, const char *remote_url, const char *auth_token) ATTR_NONNULL(1
bool BKE_blender_project_config_file_write(Main *bmain)
bool RNA_enum_id_from_value(const EnumPropertyItem *item, int value, const char **r_identifier)
bool BLI_is_dir(const char *path) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL()
Definition storage.cc:457
bool BKE_blender_project_init(blender::StringRef name, blender::StringRef root_path)
bool RNA_enum_value_from_identifier(const EnumPropertyItem *item, const char *identifier, int *r_value)
const EnumPropertyItem rna_enum_project_variable_string_subtype_items[]
char * BLI_strdup(const char *str) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL(1) ATTR_MALLOC
static CLG_LogRef LOG
Definition logging.cpp:12
bool BLI_is_file(const char *path) ATTR_WARN_UNUSED_RESULT ATTR_NONNULL()
Definition storage.cc:469
bool BKE_blender_project_init_from_root_path(Main *bmain, std::string project_root_path)
ATTR_WARN_UNUSED_RESULT const BMVert const BMEdge * e
void from_toml(const toml::value &v)
ProjectVariableStringSubtype subtype
#define SEP_STR
Definition unit.cc:41