1 /**
2 	Representing a full project, with a root Package and several dependencies.
3 
4 	Copyright: © 2012-2013 Matthias Dondorff, 2012-2016 Sönke Ludwig
5 	License: Subject to the terms of the MIT license, as written in the included LICENSE.txt file.
6 	Authors: Matthias Dondorff, Sönke Ludwig
7 */
8 module dub.project;
9 
10 import dub.compilers.compiler;
11 import dub.dependency;
12 import dub.description;
13 import dub.internal.utils;
14 import dub.internal.vibecompat.core.file;
15 import dub.internal.vibecompat.core.log;
16 import dub.internal.vibecompat.data.json;
17 import dub.internal.vibecompat.inet.path;
18 import dub.package_;
19 import dub.packagemanager;
20 import dub.generators.generator;
21 
22 import std.algorithm;
23 import std.array;
24 import std.conv : to;
25 import std.datetime;
26 import std.exception : enforce;
27 import std..string;
28 import std.encoding : sanitize;
29 
30 /**
31 	Represents a full project, a root package with its dependencies and package
32 	selection.
33 
34 	All dependencies must be available locally so that the package dependency
35 	graph can be built. Use `Project.reinit` if necessary for reloading
36 	dependencies after more packages are available.
37 */
38 class Project {
39 	private {
40 		PackageManager m_packageManager;
41 		Json m_packageSettings;
42 		Package m_rootPackage;
43 		Package[] m_dependencies;
44 		Package[][Package] m_dependees;
45 		SelectedVersions m_selections;
46 		string[] m_missingDependencies;
47 		string[string] m_overriddenConfigs;
48 	}
49 
50 	/** Loads a project.
51 
52 		Params:
53 			package_manager = Package manager instance to use for loading
54 				dependencies
55 			project_path = Path of the root package to load
56 			pack = An existing `Package` instance to use as the root package
57 	*/
58 	this(PackageManager package_manager, NativePath project_path)
59 	{
60 		Package pack;
61 		auto packageFile = Package.findPackageFile(project_path);
62 		if (packageFile.empty) {
63 			logWarn("There was no package description found for the application in '%s'.", project_path.toNativeString());
64 			pack = new Package(PackageRecipe.init, project_path);
65 		} else {
66 			pack = package_manager.getOrLoadPackage(project_path, packageFile);
67 		}
68 
69 		this(package_manager, pack);
70 	}
71 
72 	/// ditto
73 	this(PackageManager package_manager, Package pack)
74 	{
75 		m_packageManager = package_manager;
76 		m_rootPackage = pack;
77 		m_packageSettings = Json.emptyObject;
78 
79 		try m_packageSettings = jsonFromFile(m_rootPackage.path ~ ".dub/dub.json", true);
80 		catch(Exception t) logDiagnostic("Failed to read .dub/dub.json: %s", t.msg);
81 
82 		auto selverfile = m_rootPackage.path ~ SelectedVersions.defaultFile;
83 		if (existsFile(selverfile)) {
84 			try m_selections = new SelectedVersions(selverfile);
85 			catch(Exception e) {
86 				logWarn("Failed to load %s: %s", SelectedVersions.defaultFile, e.msg);
87 				logDiagnostic("Full error: %s", e.toString().sanitize);
88 				m_selections = new SelectedVersions;
89 			}
90 		} else m_selections = new SelectedVersions;
91 
92 		reinit();
93 	}
94 
95 	/** List of all resolved dependencies.
96 
97 		This includes all direct and indirect dependencies of all configurations
98 		combined. Optional dependencies that were not chosen are not included.
99 	*/
100 	@property const(Package[]) dependencies() const { return m_dependencies; }
101 
102 	/// The root package of the project.
103 	@property inout(Package) rootPackage() inout { return m_rootPackage; }
104 
105 	/// The versions to use for all dependencies. Call reinit() after changing these.
106 	@property inout(SelectedVersions) selections() inout { return m_selections; }
107 
108 	/// Package manager instance used by the project.
109 	@property inout(PackageManager) packageManager() inout { return m_packageManager; }
110 
111 	/** Determines if all dependencies necessary to build have been collected.
112 
113 		If this function returns `false`, it may be necessary to add more entries
114 		to `selections`, or to use `Dub.upgrade` to automatically select all
115 		missing dependencies.
116 	*/
117 	bool hasAllDependencies() const { return m_missingDependencies.length == 0; }
118 
119 	/// Sorted list of missing dependencies.
120 	string[] missingDependencies() { return m_missingDependencies; }
121 
122 	/** Allows iteration of the dependency tree in topological order
123 	*/
124 	int delegate(int delegate(ref Package)) getTopologicalPackageList(bool children_first = false, Package root_package = null, string[string] configs = null)
125 	{
126 		// ugly way to avoid code duplication since inout isn't compatible with foreach type inference
127 		return cast(int delegate(int delegate(ref Package)))(cast(const)this).getTopologicalPackageList(children_first, root_package, configs);
128 	}
129 	/// ditto
130 	int delegate(int delegate(ref const Package)) getTopologicalPackageList(bool children_first = false, in Package root_package = null, string[string] configs = null)
131 	const {
132 		const(Package) rootpack = root_package ? root_package : m_rootPackage;
133 
134 		int iterator(int delegate(ref const Package) del)
135 		{
136 			int ret = 0;
137 			bool[const(Package)] visited;
138 			void perform_rec(in Package p){
139 				if( p in visited ) return;
140 				visited[p] = true;
141 
142 				if( !children_first ){
143 					ret = del(p);
144 					if( ret ) return;
145 				}
146 
147 				auto cfg = configs.get(p.name, null);
148 
149 				PackageDependency[] deps;
150 				if (!cfg.length) deps = p.getAllDependencies();
151 				else {
152 					auto depmap = p.getDependencies(cfg);
153 					deps = depmap.byKey.map!(k => PackageDependency(k, depmap[k])).array;
154 				}
155 				deps.sort!((a, b) => a.name < b.name);
156 
157 				foreach (d; deps) {
158 					auto dependency = getDependency(d.name, true);
159 					assert(dependency || d.spec.optional,
160 						format("Non-optional dependency '%s' of '%s' not found in dependency tree!?.", d.name, p.name));
161 					if(dependency) perform_rec(dependency);
162 					if( ret ) return;
163 				}
164 
165 				if( children_first ){
166 					ret = del(p);
167 					if( ret ) return;
168 				}
169 			}
170 			perform_rec(rootpack);
171 			return ret;
172 		}
173 
174 		return &iterator;
175 	}
176 
177 	/** Retrieves a particular dependency by name.
178 
179 		Params:
180 			name = (Qualified) package name of the dependency
181 			is_optional = If set to true, will return `null` for unsatisfiable
182 				dependencies instead of throwing an exception.
183 	*/
184 	inout(Package) getDependency(string name, bool is_optional)
185 	inout {
186 		foreach(dp; m_dependencies)
187 			if( dp.name == name )
188 				return dp;
189 		if (!is_optional) throw new Exception("Unknown dependency: "~name);
190 		else return null;
191 	}
192 
193 	/** Returns the name of the default build configuration for the specified
194 		target platform.
195 
196 		Params:
197 			platform = The target build platform
198 			allow_non_library_configs = If set to true, will use the first
199 				possible configuration instead of the first "executable"
200 				configuration.
201 	*/
202 	string getDefaultConfiguration(BuildPlatform platform, bool allow_non_library_configs = true)
203 	const {
204 		auto cfgs = getPackageConfigs(platform, null, allow_non_library_configs);
205 		return cfgs[m_rootPackage.name];
206 	}
207 
208 	/** Overrides the configuration chosen for a particular package in the
209 		dependency graph.
210 
211 		Setting a certain configuration here is equivalent to removing all
212 		but one configuration from the package.
213 
214 		Params:
215 			package_ = The package for which to force selecting a certain
216 				dependency
217 			config = Name of the configuration to force
218 	*/
219 	void overrideConfiguration(string package_, string config)
220 	{
221 		auto p = getDependency(package_, true);
222 		enforce(p !is null,
223 			format("Package '%s', marked for configuration override, is not present in dependency graph.", package_));
224 		enforce(p.configurations.canFind(config),
225 			format("Package '%s' does not have a configuration named '%s'.", package_, config));
226 		m_overriddenConfigs[package_] = config;
227 	}
228 
229 	/** Performs basic validation of various aspects of the package.
230 
231 		This will emit warnings to `stderr` if any discouraged names or
232 		dependency patterns are found.
233 	*/
234 	void validate()
235 	{
236 		// some basic package lint
237 		m_rootPackage.warnOnSpecialCompilerFlags();
238 		string nameSuggestion() {
239 			string ret;
240 			ret ~= `Please modify the "name" field in %s accordingly.`.format(m_rootPackage.recipePath.toNativeString());
241 			if (!m_rootPackage.recipe.buildSettings.targetName.length) {
242 				if (m_rootPackage.recipePath.head.name.endsWith(".sdl")) {
243 					ret ~= ` You can then add 'targetName "%s"' to keep the current executable name.`.format(m_rootPackage.name);
244 				} else {
245 					ret ~= ` You can then add '"targetName": "%s"' to keep the current executable name.`.format(m_rootPackage.name);
246 				}
247 			}
248 			return ret;
249 		}
250 		if (m_rootPackage.name != m_rootPackage.name.toLower()) {
251 			logWarn(`WARNING: DUB package names should always be lower case. %s`, nameSuggestion());
252 		} else if (!m_rootPackage.recipe.name.all!(ch => ch >= 'a' && ch <= 'z' || ch >= '0' && ch <= '9' || ch == '-' || ch == '_')) {
253 			logWarn(`WARNING: DUB package names may only contain alphanumeric characters, `
254 				~ `as well as '-' and '_'. %s`, nameSuggestion());
255 		}
256 		enforce(!m_rootPackage.name.canFind(' '), "Aborting due to the package name containing spaces.");
257 
258 		foreach (d; m_rootPackage.getAllDependencies())
259 			if (d.spec.isExactVersion && d.spec.version_.isBranch && d.spec.repository.empty) {
260 				logWarn("WARNING: A deprecated branch based version specification is used "
261 					~ "for the dependency %s. Please use numbered versions instead. Also "
262 					~ "note that you can still use the %s file to override a certain "
263 					~ "dependency to use a branch instead.",
264 					d.name, SelectedVersions.defaultFile);
265 			}
266 
267 		// search for orphan sub configurations
268 		void warnSubConfig(string pack, string config) {
269 			logWarn("The sub configuration directive \"%s\" -> \"%s\" "
270 				~ "references a package that is not specified as a dependency "
271 				~ "and will have no effect.", pack, config);
272 		}
273 		void checkSubConfig(string pack, string config) {
274 			auto p = getDependency(pack, true);
275 			if (p && !p.configurations.canFind(config)) {
276 				logWarn("The sub configuration directive \"%s\" -> \"%s\" "
277 					~ "references a configuration that does not exist.",
278 					pack, config);
279 			}
280 		}
281 		auto globalbs = m_rootPackage.getBuildSettings();
282 		foreach (p, c; globalbs.subConfigurations) {
283 			if (p !in globalbs.dependencies) warnSubConfig(p, c);
284 			else checkSubConfig(p, c);
285 		}
286 		foreach (c; m_rootPackage.configurations) {
287 			auto bs = m_rootPackage.getBuildSettings(c);
288 			foreach (p, subConf; bs.subConfigurations) {
289 				if (p !in bs.dependencies && p !in globalbs.dependencies)
290 					warnSubConfig(p, subConf);
291 				else checkSubConfig(p, subConf);
292 			}
293 		}
294 
295 		// check for version specification mismatches
296 		bool[Package] visited;
297 		void validateDependenciesRec(Package pack) {
298 			// perform basic package linting
299 			pack.simpleLint();
300 
301 			foreach (d; pack.getAllDependencies()) {
302 				auto basename = getBasePackageName(d.name);
303 				if (m_selections.hasSelectedVersion(basename)) {
304 					auto selver = m_selections.getSelectedVersion(basename);
305 					if (d.spec.merge(selver) == Dependency.invalid) {
306 						logWarn("Selected package %s %s does not match the dependency specification %s in package %s. Need to \"dub upgrade\"?",
307 							basename, selver, d.spec, pack.name);
308 					}
309 				}
310 
311 				auto deppack = getDependency(d.name, true);
312 				if (deppack in visited) continue;
313 				visited[deppack] = true;
314 				if (deppack) validateDependenciesRec(deppack);
315 			}
316 		}
317 		validateDependenciesRec(m_rootPackage);
318 	}
319 
320 	/// Reloads dependencies.
321 	void reinit()
322 	{
323 		m_dependencies = null;
324 		m_missingDependencies = [];
325 		m_packageManager.refresh(false);
326 
327 		void collectDependenciesRec(Package pack, int depth = 0)
328 		{
329 			auto indent = replicate("  ", depth);
330 			logDebug("%sCollecting dependencies for %s", indent, pack.name);
331 			indent ~= "  ";
332 
333 			foreach (dep; pack.getAllDependencies()) {
334 				Dependency vspec = dep.spec;
335 				Package p;
336 
337 				auto basename = getBasePackageName(dep.name);
338 				auto subname = getSubPackageName(dep.name);
339 
340 				// non-optional and optional-default dependencies (if no selections file exists)
341 				// need to be satisfied
342 				bool is_desired = !vspec.optional || m_selections.hasSelectedVersion(basename) || (vspec.default_ && m_selections.bare);
343 
344 				Package resolveSubPackage(Package p, in bool silentFail) {
345 					return subname.length ? m_packageManager.getSubPackage(p, subname, silentFail) : p;
346 				}
347 
348 				if (dep.name == m_rootPackage.basePackage.name) {
349 					vspec = Dependency(m_rootPackage.version_);
350 					p = m_rootPackage.basePackage;
351 				} else if (basename == m_rootPackage.basePackage.name) {
352 					vspec = Dependency(m_rootPackage.version_);
353 					try p = m_packageManager.getSubPackage(m_rootPackage.basePackage, subname, false);
354 					catch (Exception e) {
355 						logDiagnostic("%sError getting sub package %s: %s", indent, dep.name, e.msg);
356 						if (is_desired) m_missingDependencies ~= dep.name;
357 						continue;
358 					}
359 				} else if (m_selections.hasSelectedVersion(basename)) {
360 					vspec = m_selections.getSelectedVersion(basename);
361 					if (!vspec.path.empty) {
362 						auto path = vspec.path;
363 						if (!path.absolute) path = m_rootPackage.path ~ path;
364 						p = m_packageManager.getOrLoadPackage(path, NativePath.init, true);
365 						p = resolveSubPackage(p, true);
366 					} else if (!vspec.repository.empty) {
367 						p = m_packageManager.loadSCMPackage(basename, vspec);
368 						p = resolveSubPackage(p, true);
369 					} else {
370 						p = m_packageManager.getBestPackage(dep.name, vspec);
371 					}
372 				} else if (m_dependencies.canFind!(d => getBasePackageName(d.name) == basename)) {
373 					auto idx = m_dependencies.countUntil!(d => getBasePackageName(d.name) == basename);
374 					auto bp = m_dependencies[idx].basePackage;
375 					vspec = Dependency(bp.path);
376 					p = resolveSubPackage(bp, false);
377 				} else {
378 					logDiagnostic("%sVersion selection for dependency %s (%s) of %s is missing.",
379 						indent, basename, dep.name, pack.name);
380 				}
381 
382 				if (!p && !vspec.repository.empty) {
383 					p = m_packageManager.loadSCMPackage(basename, vspec);
384 					resolveSubPackage(p, false);
385 				}
386 
387 				if (!p && !vspec.path.empty && is_desired) {
388 					NativePath path = vspec.path;
389 					if (!path.absolute) path = pack.path ~ path;
390 					logDiagnostic("%sAdding local %s in %s", indent, dep.name, path);
391 					p = m_packageManager.getOrLoadPackage(path, NativePath.init, true);
392 					if (p.parentPackage !is null) {
393 						logWarn("%sSub package %s must be referenced using the path to it's parent package.", indent, dep.name);
394 						p = p.parentPackage;
395 					}
396 					p = resolveSubPackage(p, false);
397 					enforce(p.name == dep.name,
398 						format("Path based dependency %s is referenced with a wrong name: %s vs. %s",
399 							path.toNativeString(), dep.name, p.name));
400 				}
401 
402 				if (!p) {
403 					logDiagnostic("%sMissing dependency %s %s of %s", indent, dep.name, vspec, pack.name);
404 					if (is_desired) m_missingDependencies ~= dep.name;
405 					continue;
406 				}
407 
408 				if (!m_dependencies.canFind(p)) {
409 					logDiagnostic("%sFound dependency %s %s", indent, dep.name, vspec.toString());
410 					m_dependencies ~= p;
411 					if (basename == m_rootPackage.basePackage.name)
412 						p.warnOnSpecialCompilerFlags();
413 					collectDependenciesRec(p, depth+1);
414 				}
415 
416 				m_dependees[p] ~= pack;
417 				//enforce(p !is null, "Failed to resolve dependency "~dep.name~" "~vspec.toString());
418 			}
419 		}
420 		collectDependenciesRec(m_rootPackage);
421 		m_missingDependencies.sort();
422 	}
423 
424 	/// Returns the name of the root package.
425 	@property string name() const { return m_rootPackage ? m_rootPackage.name : "app"; }
426 
427 	/// Returns the names of all configurations of the root package.
428 	@property string[] configurations() const { return m_rootPackage.configurations; }
429 
430 	/// Returns a map with the configuration for all packages in the dependency tree.
431 	string[string] getPackageConfigs(in BuildPlatform platform, string config, bool allow_non_library = true)
432 	const {
433 		struct Vertex { string pack, config; }
434 		struct Edge { size_t from, to; }
435 
436 		Vertex[] configs;
437 		Edge[] edges;
438 		string[][string] parents;
439 		parents[m_rootPackage.name] = null;
440 		foreach (p; getTopologicalPackageList())
441 			foreach (d; p.getAllDependencies())
442 				parents[d.name] ~= p.name;
443 
444 		size_t createConfig(string pack, string config) {
445 			foreach (i, v; configs)
446 				if (v.pack == pack && v.config == config)
447 					return i;
448 			assert(pack !in m_overriddenConfigs || config == m_overriddenConfigs[pack]);
449 			logDebug("Add config %s %s", pack, config);
450 			configs ~= Vertex(pack, config);
451 			return configs.length-1;
452 		}
453 
454 		bool haveConfig(string pack, string config) {
455 			return configs.any!(c => c.pack == pack && c.config == config);
456 		}
457 
458 		size_t createEdge(size_t from, size_t to) {
459 			auto idx = edges.countUntil(Edge(from, to));
460 			if (idx >= 0) return idx;
461 			logDebug("Including %s %s -> %s %s", configs[from].pack, configs[from].config, configs[to].pack, configs[to].config);
462 			edges ~= Edge(from, to);
463 			return edges.length-1;
464 		}
465 
466 		void removeConfig(size_t i) {
467 			logDebug("Eliminating config %s for %s", configs[i].config, configs[i].pack);
468 			auto had_dep_to_pack = new bool[configs.length];
469 			auto still_has_dep_to_pack = new bool[configs.length];
470 
471 			edges = edges.filter!((e) {
472 					if (e.to == i) {
473 						had_dep_to_pack[e.from] = true;
474 						return false;
475 					} else if (configs[e.to].pack == configs[i].pack) {
476 						still_has_dep_to_pack[e.from] = true;
477 					}
478 					if (e.from == i) return false;
479 					return true;
480 				}).array;
481 
482 			configs[i] = Vertex.init; // mark config as removed
483 
484 			// also remove any configs that cannot be satisfied anymore
485 			foreach (j; 0 .. configs.length)
486 				if (j != i && had_dep_to_pack[j] && !still_has_dep_to_pack[j])
487 					removeConfig(j);
488 		}
489 
490 		bool isReachable(string pack, string conf) {
491 			if (pack == configs[0].pack && configs[0].config == conf) return true;
492 			foreach (e; edges)
493 				if (configs[e.to].pack == pack && configs[e.to].config == conf)
494 					return true;
495 			return false;
496 			//return (pack == configs[0].pack && conf == configs[0].config) || edges.canFind!(e => configs[e.to].pack == pack && configs[e.to].config == config);
497 		}
498 
499 		bool isReachableByAllParentPacks(size_t cidx) {
500 			bool[string] r;
501 			foreach (p; parents[configs[cidx].pack]) r[p] = false;
502 			foreach (e; edges) {
503 				if (e.to != cidx) continue;
504 				if (auto pp = configs[e.from].pack in r) *pp = true;
505 			}
506 			foreach (bool v; r) if (!v) return false;
507 			return true;
508 		}
509 
510 		string[] allconfigs_path;
511 
512 		void determineDependencyConfigs(in Package p, string c)
513 		{
514 			string[][string] depconfigs;
515 			foreach (d; p.getAllDependencies()) {
516 				auto dp = getDependency(d.name, true);
517 				if (!dp) continue;
518 
519 				string[] cfgs;
520 				if (auto pc = dp.name in m_overriddenConfigs) cfgs = [*pc];
521 				else {
522 					auto subconf = p.getSubConfiguration(c, dp, platform);
523 					if (!subconf.empty) cfgs = [subconf];
524 					else cfgs = dp.getPlatformConfigurations(platform);
525 				}
526 				cfgs = cfgs.filter!(c => haveConfig(d.name, c)).array;
527 
528 				// if no valid configuration was found for a dependency, don't include the
529 				// current configuration
530 				if (!cfgs.length) {
531 					logDebug("Skip %s %s (missing configuration for %s)", p.name, c, dp.name);
532 					return;
533 				}
534 				depconfigs[d.name] = cfgs;
535 			}
536 
537 			// add this configuration to the graph
538 			size_t cidx = createConfig(p.name, c);
539 			foreach (d; p.getAllDependencies())
540 				foreach (sc; depconfigs.get(d.name, null))
541 					createEdge(cidx, createConfig(d.name, sc));
542 		}
543 
544 		// create a graph of all possible package configurations (package, config) -> (subpackage, subconfig)
545 		void determineAllConfigs(in Package p)
546 		{
547 			auto idx = allconfigs_path.countUntil(p.name);
548 			enforce(idx < 0, format("Detected dependency cycle: %s", (allconfigs_path[idx .. $] ~ p.name).join("->")));
549 			allconfigs_path ~= p.name;
550 			scope (exit) allconfigs_path.length--;
551 
552 			// first, add all dependency configurations
553 			foreach (d; p.getAllDependencies) {
554 				auto dp = getDependency(d.name, true);
555 				if (!dp) continue;
556 				determineAllConfigs(dp);
557 			}
558 
559 			// for each configuration, determine the configurations usable for the dependencies
560 			if (auto pc = p.name in m_overriddenConfigs)
561 				determineDependencyConfigs(p, *pc);
562 			else
563 				foreach (c; p.getPlatformConfigurations(platform, p is m_rootPackage && allow_non_library))
564 					determineDependencyConfigs(p, c);
565 		}
566 		if (config.length) createConfig(m_rootPackage.name, config);
567 		determineAllConfigs(m_rootPackage);
568 
569 		// successively remove configurations until only one configuration per package is left
570 		bool changed;
571 		do {
572 			// remove all configs that are not reachable by all parent packages
573 			changed = false;
574 			foreach (i, ref c; configs) {
575 				if (c == Vertex.init) continue; // ignore deleted configurations
576 				if (!isReachableByAllParentPacks(i)) {
577 					logDebug("%s %s NOT REACHABLE by all of (%s):", c.pack, c.config, parents[c.pack]);
578 					removeConfig(i);
579 					changed = true;
580 				}
581 			}
582 
583 			// when all edges are cleaned up, pick one package and remove all but one config
584 			if (!changed) {
585 				foreach (p; getTopologicalPackageList()) {
586 					size_t cnt = 0;
587 					foreach (i, ref c; configs)
588 						if (c.pack == p.name && ++cnt > 1) {
589 							logDebug("NON-PRIMARY: %s %s", c.pack, c.config);
590 							removeConfig(i);
591 						}
592 					if (cnt > 1) {
593 						changed = true;
594 						break;
595 					}
596 				}
597 			}
598 		} while (changed);
599 
600 		// print out the resulting tree
601 		foreach (e; edges) logDebug("    %s %s -> %s %s", configs[e.from].pack, configs[e.from].config, configs[e.to].pack, configs[e.to].config);
602 
603 		// return the resulting configuration set as an AA
604 		string[string] ret;
605 		foreach (c; configs) {
606 			if (c == Vertex.init) continue; // ignore deleted configurations
607 			assert(ret.get(c.pack, c.config) == c.config, format("Conflicting configurations for %s found: %s vs. %s", c.pack, c.config, ret[c.pack]));
608 			logDebug("Using configuration '%s' for %s", c.config, c.pack);
609 			ret[c.pack] = c.config;
610 		}
611 
612 		// check for conflicts (packages missing in the final configuration graph)
613 		void checkPacksRec(in Package pack) {
614 			auto pc = pack.name in ret;
615 			enforce(pc !is null, "Could not resolve configuration for package "~pack.name);
616 			foreach (p, dep; pack.getDependencies(*pc)) {
617 				auto deppack = getDependency(p, dep.optional);
618 				if (deppack) checkPacksRec(deppack);
619 			}
620 		}
621 		checkPacksRec(m_rootPackage);
622 
623 		return ret;
624 	}
625 
626 	/**
627 	 * Fills `dst` with values from this project.
628 	 *
629 	 * `dst` gets initialized according to the given platform and config.
630 	 *
631 	 * Params:
632 	 *   dst = The BuildSettings struct to fill with data.
633 	 *   gsettings = The generator settings to retrieve the values for.
634 	 *   config = Values of the given configuration will be retrieved.
635 	 *   root_package = If non null, use it instead of the project's real root package.
636 	 *   shallow = If true, collects only build settings for the main package (including inherited settings) and doesn't stop on target type none and sourceLibrary.
637 	 */
638 	void addBuildSettings(ref BuildSettings dst, in GeneratorSettings gsettings, string config, in Package root_package = null, bool shallow = false)
639 	const {
640 		import dub.internal.utils : stripDlangSpecialChars;
641 
642 		auto configs = getPackageConfigs(gsettings.platform, config);
643 
644 		foreach (pkg; this.getTopologicalPackageList(false, root_package, configs)) {
645 			auto pkg_path = pkg.path.toNativeString();
646 			dst.addVersions(["Have_" ~ stripDlangSpecialChars(pkg.name)]);
647 
648 			assert(pkg.name in configs, "Missing configuration for "~pkg.name);
649 			logDebug("Gathering build settings for %s (%s)", pkg.name, configs[pkg.name]);
650 
651 			auto psettings = pkg.getBuildSettings(gsettings.platform, configs[pkg.name]);
652 			if (psettings.targetType != TargetType.none) {
653 				if (shallow && pkg !is m_rootPackage)
654 					psettings.sourceFiles = null;
655 				processVars(dst, this, pkg, psettings, gsettings);
656 				if (!gsettings.single && psettings.importPaths.empty)
657 					logWarn(`Package %s (configuration "%s") defines no import paths, use {"importPaths": [...]} or the default package directory structure to fix this.`, pkg.name, configs[pkg.name]);
658 				if (psettings.mainSourceFile.empty && pkg is m_rootPackage && psettings.targetType == TargetType.executable)
659 					logWarn(`Executable configuration "%s" of package %s defines no main source file, this may cause certain build modes to fail. Add an explicit "mainSourceFile" to the package description to fix this.`, configs[pkg.name], pkg.name);
660 			}
661 			if (pkg is m_rootPackage) {
662 				if (!shallow) {
663 					enforce(psettings.targetType != TargetType.none, "Main package has target type \"none\" - stopping build.");
664 					enforce(psettings.targetType != TargetType.sourceLibrary, "Main package has target type \"sourceLibrary\" which generates no target - stopping build.");
665 				}
666 				dst.targetType = psettings.targetType;
667 				dst.targetPath = psettings.targetPath;
668 				dst.targetName = psettings.targetName;
669 				if (!psettings.workingDirectory.empty)
670 					dst.workingDirectory = processVars(psettings.workingDirectory, this, pkg, gsettings, true, [dst.environments, dst.buildEnvironments]);
671 				if (psettings.mainSourceFile.length)
672 					dst.mainSourceFile = processVars(psettings.mainSourceFile, this, pkg, gsettings, true, [dst.environments, dst.buildEnvironments]);
673 			}
674 		}
675 
676 		// always add all version identifiers of all packages
677 		foreach (pkg; this.getTopologicalPackageList(false, null, configs)) {
678 			auto psettings = pkg.getBuildSettings(gsettings.platform, configs[pkg.name]);
679 			dst.addVersions(psettings.versions);
680 		}
681 	}
682 
683 	/** Fills `dst` with build settings specific to the given build type.
684 
685 		Params:
686 			dst = The `BuildSettings` instance to add the build settings to
687 			gsettings = Target generator settings
688 			build_type = Name of the build type
689 			for_root_package = Selects if the build settings are for the root
690 				package or for one of the dependencies. Unittest flags will
691 				only be added to the root package.
692 	*/
693 	void addBuildTypeSettings(ref BuildSettings dst, in GeneratorSettings gsettings, bool for_root_package = true)
694 	{
695 		bool usedefflags = !(dst.requirements & BuildRequirement.noDefaultFlags);
696 		if (usedefflags) {
697 			BuildSettings btsettings;
698 			m_rootPackage.addBuildTypeSettings(btsettings, gsettings.platform, gsettings.buildType);
699 
700 			if (!for_root_package) {
701 				// don't propagate unittest switch to dependencies, as dependent
702 				// unit tests aren't run anyway and the additional code may
703 				// cause linking to fail on Windows (issue #640)
704 				btsettings.removeOptions(BuildOption.unittests);
705 			}
706 
707 			processVars(dst, this, m_rootPackage, btsettings, gsettings);
708 		}
709 	}
710 
711 	/// Outputs a build description of the project, including its dependencies.
712 	ProjectDescription describe(GeneratorSettings settings)
713 	{
714 		import dub.generators.targetdescription;
715 
716 		// store basic build parameters
717 		ProjectDescription ret;
718 		ret.rootPackage = m_rootPackage.name;
719 		ret.configuration = settings.config;
720 		ret.buildType = settings.buildType;
721 		ret.compiler = settings.platform.compiler;
722 		ret.architecture = settings.platform.architecture;
723 		ret.platform = settings.platform.platform;
724 
725 		// collect high level information about projects (useful for IDE display)
726 		auto configs = getPackageConfigs(settings.platform, settings.config);
727 		ret.packages ~= m_rootPackage.describe(settings.platform, settings.config);
728 		foreach (dep; m_dependencies)
729 			ret.packages ~= dep.describe(settings.platform, configs[dep.name]);
730 
731 		foreach (p; getTopologicalPackageList(false, null, configs))
732 			ret.packages[ret.packages.countUntil!(pp => pp.name == p.name)].active = true;
733 
734 		if (settings.buildType.length) {
735 			// collect build target information (useful for build tools)
736 			auto gen = new TargetDescriptionGenerator(this);
737 			try {
738 				gen.generate(settings);
739 				ret.targets = gen.targetDescriptions;
740 				ret.targetLookup = gen.targetDescriptionLookup;
741 			} catch (Exception e) {
742 				logDiagnostic("Skipping targets description: %s", e.msg);
743 				logDebug("Full error: %s", e.toString().sanitize);
744 			}
745 		}
746 
747 		return ret;
748 	}
749 
750 	private string[] listBuildSetting(string attributeName)(BuildPlatform platform,
751 		string config, ProjectDescription projectDescription, Compiler compiler, bool disableEscaping)
752 	{
753 		return listBuildSetting!attributeName(platform, getPackageConfigs(platform, config),
754 			projectDescription, compiler, disableEscaping);
755 	}
756 
757 	private string[] listBuildSetting(string attributeName)(BuildPlatform platform,
758 		string[string] configs, ProjectDescription projectDescription, Compiler compiler, bool disableEscaping)
759 	{
760 		if (compiler)
761 			return formatBuildSettingCompiler!attributeName(platform, configs, projectDescription, compiler, disableEscaping);
762 		else
763 			return formatBuildSettingPlain!attributeName(platform, configs, projectDescription);
764 	}
765 
766 	// Output a build setting formatted for a compiler
767 	private string[] formatBuildSettingCompiler(string attributeName)(BuildPlatform platform,
768 		string[string] configs, ProjectDescription projectDescription, Compiler compiler, bool disableEscaping)
769 	{
770 		import std.process : escapeShellFileName;
771 		import std.path : dirSeparator;
772 
773 		assert(compiler);
774 
775 		auto targetDescription = projectDescription.lookupTarget(projectDescription.rootPackage);
776 		auto buildSettings = targetDescription.buildSettings;
777 
778 		string[] values;
779 		switch (attributeName)
780 		{
781 		case "dflags":
782 		case "linkerFiles":
783 		case "mainSourceFile":
784 		case "importFiles":
785 			values = formatBuildSettingPlain!attributeName(platform, configs, projectDescription);
786 			break;
787 
788 		case "lflags":
789 		case "sourceFiles":
790 		case "versions":
791 		case "debugVersions":
792 		case "importPaths":
793 		case "stringImportPaths":
794 		case "options":
795 			auto bs = buildSettings.dup;
796 			bs.dflags = null;
797 
798 			// Ensure trailing slash on directory paths
799 			auto ensureTrailingSlash = (string path) => path.endsWith(dirSeparator) ? path : path ~ dirSeparator;
800 			static if (attributeName == "importPaths")
801 				bs.importPaths = bs.importPaths.map!(ensureTrailingSlash).array();
802 			else static if (attributeName == "stringImportPaths")
803 				bs.stringImportPaths = bs.stringImportPaths.map!(ensureTrailingSlash).array();
804 
805 			compiler.prepareBuildSettings(bs, platform, BuildSetting.all & ~to!BuildSetting(attributeName));
806 			values = bs.dflags;
807 			break;
808 
809 		case "libs":
810 			auto bs = buildSettings.dup;
811 			bs.dflags = null;
812 			bs.lflags = null;
813 			bs.sourceFiles = null;
814 			bs.targetType = TargetType.none; // Force Compiler to NOT omit dependency libs when package is a library.
815 
816 			compiler.prepareBuildSettings(bs, platform, BuildSetting.all & ~to!BuildSetting(attributeName));
817 
818 			if (bs.lflags)
819 				values = compiler.lflagsToDFlags( bs.lflags );
820 			else if (bs.sourceFiles)
821 				values = compiler.lflagsToDFlags( bs.sourceFiles );
822 			else
823 				values = bs.dflags;
824 
825 			break;
826 
827 		default: assert(0);
828 		}
829 
830 		// Escape filenames and paths
831 		if(!disableEscaping)
832 		{
833 			switch (attributeName)
834 			{
835 			case "mainSourceFile":
836 			case "linkerFiles":
837 			case "copyFiles":
838 			case "importFiles":
839 			case "stringImportFiles":
840 			case "sourceFiles":
841 			case "importPaths":
842 			case "stringImportPaths":
843 				return values.map!(escapeShellFileName).array();
844 
845 			default:
846 				return values;
847 			}
848 		}
849 
850 		return values;
851 	}
852 
853 	// Output a build setting without formatting for any particular compiler
854 	private string[] formatBuildSettingPlain(string attributeName)(BuildPlatform platform, string[string] configs, ProjectDescription projectDescription)
855 	{
856 		import std.path : buildNormalizedPath, dirSeparator;
857 		import std.range : only;
858 
859 		string[] list;
860 
861 		enforce(attributeName == "targetType" || projectDescription.lookupRootPackage().targetType != TargetType.none,
862 			"Target type is 'none'. Cannot list build settings.");
863 
864 		static if (attributeName == "targetType")
865 			if (projectDescription.rootPackage !in projectDescription.targetLookup)
866 				return ["none"];
867 
868 		auto targetDescription = projectDescription.lookupTarget(projectDescription.rootPackage);
869 		auto buildSettings = targetDescription.buildSettings;
870 
871 		// Return any BuildSetting member attributeName as a range of strings. Don't attempt to fixup values.
872 		// allowEmptyString: When the value is a string (as opposed to string[]),
873 		//                   is empty string an actual permitted value instead of
874 		//                   a missing value?
875 		auto getRawBuildSetting(Package pack, bool allowEmptyString) {
876 			auto value = __traits(getMember, buildSettings, attributeName);
877 
878 			static if( is(typeof(value) == string[]) )
879 				return value;
880 			else static if( is(typeof(value) == string) )
881 			{
882 				auto ret = only(value);
883 
884 				// only() has a different return type from only(value), so we
885 				// have to empty the range rather than just returning only().
886 				if(value.empty && !allowEmptyString) {
887 					ret.popFront();
888 					assert(ret.empty);
889 				}
890 
891 				return ret;
892 			}
893 			else static if( is(typeof(value) == string[string]) )
894 				return value.byKeyValue.map!(a => a.key ~ "=" ~ a.value);
895 			else static if( is(typeof(value) == enum) )
896 				return only(value);
897 			else static if( is(typeof(value) == BuildRequirements) )
898 				return only(cast(BuildRequirement) cast(int) value.values);
899 			else static if( is(typeof(value) == BuildOptions) )
900 				return only(cast(BuildOption) cast(int) value.values);
901 			else
902 				static assert(false, "Type of BuildSettings."~attributeName~" is unsupported.");
903 		}
904 
905 		// Adjust BuildSetting member attributeName as needed.
906 		// Returns a range of strings.
907 		auto getFixedBuildSetting(Package pack) {
908 			// Is relative path(s) to a directory?
909 			enum isRelativeDirectory =
910 				attributeName == "importPaths" || attributeName == "stringImportPaths" ||
911 				attributeName == "targetPath" || attributeName == "workingDirectory";
912 
913 			// Is relative path(s) to a file?
914 			enum isRelativeFile =
915 				attributeName == "sourceFiles" || attributeName == "linkerFiles" ||
916 				attributeName == "importFiles" || attributeName == "stringImportFiles" ||
917 				attributeName == "copyFiles" || attributeName == "mainSourceFile";
918 
919 			// For these, empty string means "main project directory", not "missing value"
920 			enum allowEmptyString =
921 				attributeName == "targetPath" || attributeName == "workingDirectory";
922 
923 			enum isEnumBitfield =
924 				attributeName == "requirements" || attributeName == "options";
925 
926 			enum isEnum = attributeName == "targetType";
927 
928 			auto values = getRawBuildSetting(pack, allowEmptyString);
929 			string fixRelativePath(string importPath) { return buildNormalizedPath(pack.path.toString(), importPath); }
930 			static string ensureTrailingSlash(string path) { return path.endsWith(dirSeparator) ? path : path ~ dirSeparator; }
931 
932 			static if(isRelativeDirectory) {
933 				// Return full paths for the paths, making sure a
934 				// directory separator is on the end of each path.
935 				return values.map!(fixRelativePath).map!(ensureTrailingSlash);
936 			}
937 			else static if(isRelativeFile) {
938 				// Return full paths.
939 				return values.map!(fixRelativePath);
940 			}
941 			else static if(isEnumBitfield)
942 				return bitFieldNames(values.front);
943 			else static if (isEnum)
944 				return [values.front.to!string];
945 			else
946 				return values;
947 		}
948 
949 		foreach(value; getFixedBuildSetting(m_rootPackage)) {
950 			list ~= value;
951 		}
952 
953 		return list;
954 	}
955 
956 	// The "compiler" arg is for choosing which compiler the output should be formatted for,
957 	// or null to imply "list" format.
958 	private string[] listBuildSetting(BuildPlatform platform, string[string] configs,
959 		ProjectDescription projectDescription, string requestedData, Compiler compiler, bool disableEscaping)
960 	{
961 		// Certain data cannot be formatter for a compiler
962 		if (compiler)
963 		{
964 			switch (requestedData)
965 			{
966 			case "target-type":
967 			case "target-path":
968 			case "target-name":
969 			case "working-directory":
970 			case "string-import-files":
971 			case "copy-files":
972 			case "extra-dependency-files":
973 			case "pre-generate-commands":
974 			case "post-generate-commands":
975 			case "pre-build-commands":
976 			case "post-build-commands":
977 			case "environments":
978 			case "build-environments":
979 			case "run-environments":
980 			case "pre-generate-environments":
981 			case "post-generate-environments":
982 			case "pre-build-environments":
983 			case "post-build-environments":
984 			case "pre-run-environments":
985 			case "post-run-environments":
986 				enforce(false, "--data="~requestedData~" can only be used with --data-list or --data-0.");
987 				break;
988 
989 			case "requirements":
990 				enforce(false, "--data=requirements can only be used with --data-list or --data-0. Use --data=options instead.");
991 				break;
992 
993 			default: break;
994 			}
995 		}
996 
997 		import std.typetuple : TypeTuple;
998 		auto args = TypeTuple!(platform, configs, projectDescription, compiler, disableEscaping);
999 		switch (requestedData)
1000 		{
1001 		case "target-type":                return listBuildSetting!"targetType"(args);
1002 		case "target-path":                return listBuildSetting!"targetPath"(args);
1003 		case "target-name":                return listBuildSetting!"targetName"(args);
1004 		case "working-directory":          return listBuildSetting!"workingDirectory"(args);
1005 		case "main-source-file":           return listBuildSetting!"mainSourceFile"(args);
1006 		case "dflags":                     return listBuildSetting!"dflags"(args);
1007 		case "lflags":                     return listBuildSetting!"lflags"(args);
1008 		case "libs":                       return listBuildSetting!"libs"(args);
1009 		case "linker-files":               return listBuildSetting!"linkerFiles"(args);
1010 		case "source-files":               return listBuildSetting!"sourceFiles"(args);
1011 		case "copy-files":                 return listBuildSetting!"copyFiles"(args);
1012 		case "extra-dependency-files":     return listBuildSetting!"extraDependencyFiles"(args);
1013 		case "versions":                   return listBuildSetting!"versions"(args);
1014 		case "debug-versions":             return listBuildSetting!"debugVersions"(args);
1015 		case "import-paths":               return listBuildSetting!"importPaths"(args);
1016 		case "string-import-paths":        return listBuildSetting!"stringImportPaths"(args);
1017 		case "import-files":               return listBuildSetting!"importFiles"(args);
1018 		case "string-import-files":        return listBuildSetting!"stringImportFiles"(args);
1019 		case "pre-generate-commands":      return listBuildSetting!"preGenerateCommands"(args);
1020 		case "post-generate-commands":     return listBuildSetting!"postGenerateCommands"(args);
1021 		case "pre-build-commands":         return listBuildSetting!"preBuildCommands"(args);
1022 		case "post-build-commands":        return listBuildSetting!"postBuildCommands"(args);
1023 		case "pre-run-commands":           return listBuildSetting!"preRunCommands"(args);
1024 		case "post-run-commands":          return listBuildSetting!"postRunCommands"(args);
1025 		case "environments":               return listBuildSetting!"environments"(args);
1026 		case "build-environments":         return listBuildSetting!"buildEnvironments"(args);
1027 		case "run-environments":           return listBuildSetting!"runEnvironments"(args);
1028 		case "pre-generate-environments":  return listBuildSetting!"preGenerateEnvironments"(args);
1029 		case "post-generate-environments": return listBuildSetting!"postGenerateEnvironments"(args);
1030 		case "pre-build-environments":     return listBuildSetting!"preBuildEnvironments"(args);
1031 		case "post-build-environments":    return listBuildSetting!"postBuildEnvironments"(args);
1032 		case "pre-run-environments":       return listBuildSetting!"preRunEnvironments"(args);
1033 		case "post-run-environments":      return listBuildSetting!"postRunEnvironments"(args);
1034 		case "requirements":               return listBuildSetting!"requirements"(args);
1035 		case "options":                    return listBuildSetting!"options"(args);
1036 
1037 		default:
1038 			enforce(false, "--data="~requestedData~
1039 				" is not a valid option. See 'dub describe --help' for accepted --data= values.");
1040 		}
1041 
1042 		assert(0);
1043 	}
1044 
1045 	/// Outputs requested data for the project, optionally including its dependencies.
1046 	string[] listBuildSettings(GeneratorSettings settings, string[] requestedData, ListBuildSettingsFormat list_type)
1047 	{
1048 		import dub.compilers.utils : isLinkerFile;
1049 
1050 		auto projectDescription = describe(settings);
1051 		auto configs = getPackageConfigs(settings.platform, settings.config);
1052 		PackageDescription packageDescription;
1053 		foreach (pack; projectDescription.packages) {
1054 			if (pack.name == projectDescription.rootPackage)
1055 				packageDescription = pack;
1056 		}
1057 
1058 		if (projectDescription.rootPackage in projectDescription.targetLookup) {
1059 			// Copy linker files from sourceFiles to linkerFiles
1060 			auto target = projectDescription.lookupTarget(projectDescription.rootPackage);
1061 			foreach (file; target.buildSettings.sourceFiles.filter!(f => isLinkerFile(settings.platform, f)))
1062 				target.buildSettings.addLinkerFiles(file);
1063 
1064 			// Remove linker files from sourceFiles
1065 			target.buildSettings.sourceFiles =
1066 				target.buildSettings.sourceFiles
1067 				.filter!(a => !isLinkerFile(settings.platform, a))
1068 				.array();
1069 			projectDescription.lookupTarget(projectDescription.rootPackage) = target;
1070 		}
1071 
1072 		Compiler compiler;
1073 		bool no_escape;
1074 		final switch (list_type) with (ListBuildSettingsFormat) {
1075 			case list: break;
1076 			case listNul: no_escape = true; break;
1077 			case commandLine: compiler = settings.compiler; break;
1078 			case commandLineNul: compiler = settings.compiler; no_escape = true; break;
1079 
1080 		}
1081 
1082 		auto result = requestedData
1083 			.map!(dataName => listBuildSetting(settings.platform, configs, projectDescription, dataName, compiler, no_escape));
1084 
1085 		final switch (list_type) with (ListBuildSettingsFormat) {
1086 			case list: return result.map!(l => l.join("\n")).array();
1087 			case listNul: return result.map!(l => l.join("\0")).array;
1088 			case commandLine: return result.map!(l => l.join(" ")).array;
1089 			case commandLineNul: return result.map!(l => l.join("\0")).array;
1090 		}
1091 	}
1092 
1093 	/** Saves the currently selected dependency versions to disk.
1094 
1095 		The selections will be written to a file named
1096 		`SelectedVersions.defaultFile` ("dub.selections.json") within the
1097 		directory of the root package. Any existing file will get overwritten.
1098 	*/
1099 	void saveSelections()
1100 	{
1101 		assert(m_selections !is null, "Cannot save selections for non-disk based project (has no selections).");
1102 		if (m_selections.hasSelectedVersion(m_rootPackage.basePackage.name))
1103 			m_selections.deselectVersion(m_rootPackage.basePackage.name);
1104 
1105 		auto path = m_rootPackage.path ~ SelectedVersions.defaultFile;
1106 		if (m_selections.dirty || !existsFile(path))
1107 			m_selections.save(path);
1108 	}
1109 
1110 	deprecated bool isUpgradeCacheUpToDate()
1111 	{
1112 		return false;
1113 	}
1114 
1115 	deprecated Dependency[string] getUpgradeCache()
1116 	{
1117 		return null;
1118 	}
1119 
1120 	/** Sets a new set of versions for the upgrade cache.
1121 	*/
1122 	void setUpgradeCache(Dependency[string] versions)
1123 	{
1124 		logDebug("markUpToDate");
1125 		Json create(ref Json json, string object) {
1126 			if (json[object].type == Json.Type.undefined) json[object] = Json.emptyObject;
1127 			return json[object];
1128 		}
1129 		create(m_packageSettings, "dub");
1130 		m_packageSettings["dub"]["lastUpgrade"] = Clock.currTime().toISOExtString();
1131 
1132 		create(m_packageSettings["dub"], "cachedUpgrades");
1133 		foreach (p, d; versions)
1134 			m_packageSettings["dub"]["cachedUpgrades"][p] = SelectedVersions.dependencyToJson(d);
1135 
1136 		writeDubJson();
1137 	}
1138 
1139 	private void writeDubJson() {
1140 		import std.file : exists, mkdir;
1141 		// don't bother to write an empty file
1142 		if( m_packageSettings.length == 0 ) return;
1143 
1144 		try {
1145 			logDebug("writeDubJson");
1146 			auto dubpath = m_rootPackage.path~".dub";
1147 			if( !exists(dubpath.toNativeString()) ) mkdir(dubpath.toNativeString());
1148 			auto dstFile = openFile((dubpath~"dub.json").toString(), FileMode.createTrunc);
1149 			scope(exit) dstFile.close();
1150 			dstFile.writePrettyJsonString(m_packageSettings);
1151 		} catch( Exception e ){
1152 			logWarn("Could not write .dub/dub.json.");
1153 		}
1154 	}
1155 }
1156 
1157 
1158 /// Determines the output format used for `Project.listBuildSettings`.
1159 enum ListBuildSettingsFormat {
1160 	list,           /// Newline separated list entries
1161 	listNul,        /// NUL character separated list entries (unescaped)
1162 	commandLine,    /// Formatted for compiler command line (one data list per line)
1163 	commandLineNul, /// NUL character separated list entries (unescaped, data lists separated by two NUL characters)
1164 }
1165 
1166 
1167 /// Indicates where a package has been or should be placed to.
1168 enum PlacementLocation {
1169 	/// Packages retrieved with 'local' will be placed in the current folder
1170 	/// using the package name as destination.
1171 	local,
1172 	/// Packages with 'userWide' will be placed in a folder accessible by
1173 	/// all of the applications from the current user.
1174 	user,
1175 	/// Packages retrieved with 'systemWide' will be placed in a shared folder,
1176 	/// which can be accessed by all users of the system.
1177 	system
1178 }
1179 
1180 void processVars(ref BuildSettings dst, in Project project, in Package pack,
1181 	BuildSettings settings, in GeneratorSettings gsettings, bool include_target_settings = false)
1182 {
1183 	string[string] processVerEnvs(in string[string] targetEnvs, in string[string] defaultEnvs)
1184 	{
1185 		string[string] retEnv;
1186 		foreach (k, v; targetEnvs)
1187 			retEnv[k] = v;
1188 		foreach (k, v; defaultEnvs) {
1189 			if (k !in targetEnvs)
1190 				retEnv[k] = v;
1191 		}
1192 		return processVars(project, pack, gsettings, retEnv);
1193 	}
1194 	dst.addEnvironments(processVerEnvs(settings.environments, gsettings.buildSettings.environments));
1195 	dst.addBuildEnvironments(processVerEnvs(settings.buildEnvironments, gsettings.buildSettings.buildEnvironments));
1196 	dst.addRunEnvironments(processVerEnvs(settings.runEnvironments, gsettings.buildSettings.runEnvironments));
1197 	dst.addPreGenerateEnvironments(processVerEnvs(settings.preGenerateEnvironments, gsettings.buildSettings.preGenerateEnvironments));
1198 	dst.addPostGenerateEnvironments(processVerEnvs(settings.postGenerateEnvironments, gsettings.buildSettings.postGenerateEnvironments));
1199 	dst.addPreBuildEnvironments(processVerEnvs(settings.preBuildEnvironments, gsettings.buildSettings.preBuildEnvironments));
1200 	dst.addPostBuildEnvironments(processVerEnvs(settings.postBuildEnvironments, gsettings.buildSettings.postBuildEnvironments));
1201 	dst.addPreRunEnvironments(processVerEnvs(settings.preRunEnvironments, gsettings.buildSettings.preRunEnvironments));
1202 	dst.addPostRunEnvironments(processVerEnvs(settings.postRunEnvironments, gsettings.buildSettings.postRunEnvironments));
1203 	
1204 	auto buildEnvs = [dst.environments, dst.buildEnvironments];
1205 	auto runEnvs = [dst.environments, dst.runEnvironments];
1206 	auto preGenEnvs = [dst.environments, dst.preGenerateEnvironments];
1207 	auto postGenEnvs = [dst.environments, dst.postGenerateEnvironments];
1208 	auto preBuildEnvs = buildEnvs ~ [dst.preBuildEnvironments];
1209 	auto postBuildEnvs = buildEnvs ~ [dst.postBuildEnvironments];
1210 	auto preRunEnvs = runEnvs ~ [dst.preRunEnvironments];
1211 	auto postRunEnvs = runEnvs ~ [dst.postRunEnvironments];
1212 	
1213 	dst.addDFlags(processVars(project, pack, gsettings, settings.dflags, false, buildEnvs));
1214 	dst.addLFlags(processVars(project, pack, gsettings, settings.lflags, false, buildEnvs));
1215 	dst.addLibs(processVars(project, pack, gsettings, settings.libs, false, buildEnvs));
1216 	dst.addSourceFiles(processVars!true(project, pack, gsettings, settings.sourceFiles, true, buildEnvs));
1217 	dst.addImportFiles(processVars(project, pack, gsettings, settings.importFiles, true, buildEnvs));
1218 	dst.addStringImportFiles(processVars(project, pack, gsettings, settings.stringImportFiles, true, buildEnvs));
1219 	dst.addCopyFiles(processVars(project, pack, gsettings, settings.copyFiles, true, buildEnvs));
1220 	dst.addExtraDependencyFiles(processVars(project, pack, gsettings, settings.extraDependencyFiles, true, buildEnvs));
1221 	dst.addVersions(processVars(project, pack, gsettings, settings.versions, false, buildEnvs));
1222 	dst.addDebugVersions(processVars(project, pack, gsettings, settings.debugVersions, false, buildEnvs));
1223 	dst.addVersionFilters(processVars(project, pack, gsettings, settings.versionFilters, false, buildEnvs));
1224 	dst.addDebugVersionFilters(processVars(project, pack, gsettings, settings.debugVersionFilters, false, buildEnvs));
1225 	dst.addImportPaths(processVars(project, pack, gsettings, settings.importPaths, true, buildEnvs));
1226 	dst.addStringImportPaths(processVars(project, pack, gsettings, settings.stringImportPaths, true, buildEnvs));
1227 	dst.addPreGenerateCommands(processVars(project, pack, gsettings, settings.preGenerateCommands, false, preGenEnvs));
1228 	dst.addPostGenerateCommands(processVars(project, pack, gsettings, settings.postGenerateCommands, false, postGenEnvs));
1229 	dst.addPreBuildCommands(processVars(project, pack, gsettings, settings.preBuildCommands, false, preBuildEnvs));
1230 	dst.addPostBuildCommands(processVars(project, pack, gsettings, settings.postBuildCommands, false, postBuildEnvs));
1231 	dst.addPreRunCommands(processVars(project, pack, gsettings, settings.preRunCommands, false, preRunEnvs));
1232 	dst.addPostRunCommands(processVars(project, pack, gsettings, settings.postRunCommands, false, postRunEnvs));
1233 	dst.addRequirements(settings.requirements);
1234 	dst.addOptions(settings.options);
1235 
1236 	if (include_target_settings) {
1237 		dst.targetType = settings.targetType;
1238 		dst.targetPath = processVars(settings.targetPath, project, pack, gsettings, true, buildEnvs);
1239 		dst.targetName = settings.targetName;
1240 		if (!settings.workingDirectory.empty)
1241 			dst.workingDirectory = processVars(settings.workingDirectory, project, pack, gsettings, true, buildEnvs);
1242 		if (settings.mainSourceFile.length)
1243 			dst.mainSourceFile = processVars(settings.mainSourceFile, project, pack, gsettings, true, buildEnvs);
1244 	}
1245 }
1246 
1247 private string[] processVars(bool glob = false)(in Project project, in Package pack, in GeneratorSettings gsettings, string[] vars, bool are_paths = false, in string[string][] extraVers = null)
1248 {
1249 	auto ret = appender!(string[])();
1250 	processVars!glob(ret, project, pack, gsettings, vars, are_paths, extraVers);
1251 	return ret.data;
1252 }
1253 private void processVars(bool glob = false)(ref Appender!(string[]) dst, in Project project, in Package pack, in GeneratorSettings gsettings, string[] vars, bool are_paths = false, in string[string][] extraVers = null)
1254 {
1255 	static if (glob)
1256 		alias process = processVarsWithGlob!(Project, Package);
1257 	else
1258 		alias process = processVars!(Project, Package);
1259 	foreach (var; vars)
1260 		dst.put(process(var, project, pack, gsettings, are_paths, extraVers));
1261 }
1262 
1263 private string processVars(Project, Package)(string var, in Project project, in Package pack, in GeneratorSettings gsettings, bool is_path, in string[string][] extraVers = null)
1264 {
1265 	var = var.expandVars!(varName => getVariable(varName, project, pack, gsettings, extraVers));
1266 	if (!is_path)
1267 		return var;
1268 	auto p = NativePath(var);
1269 	if (!p.absolute)
1270 		return (pack.path ~ p).toNativeString();
1271 	else
1272 		return p.toNativeString();
1273 }
1274 private string[string] processVars(bool glob = false)(in Project project, in Package pack, in GeneratorSettings gsettings, string[string] vars, in string[string][] extraVers = null)
1275 {
1276 	string[string] ret;
1277 	processVars!glob(ret, project, pack, gsettings, vars, extraVers);
1278 	return ret;
1279 }
1280 private void processVars(bool glob = false)(ref string[string] dst, in Project project, in Package pack, in GeneratorSettings gsettings, string[string] vars, in string[string][] extraVers)
1281 {
1282 	static if (glob)
1283 		alias process = processVarsWithGlob!(Project, Package);
1284 	else
1285 		alias process = processVars!(Project, Package);
1286 	foreach (k, var; vars)
1287 		dst[k] = process(var, project, pack, gsettings, false, extraVers);
1288 }
1289 
1290 private string[] processVarsWithGlob(Project, Package)(string var, in Project project, in Package pack, in GeneratorSettings gsettings, bool is_path, in string[string][] extraVers)
1291 {
1292 	assert(is_path, "can't glob something that isn't a path");
1293 	string res = processVars(var, project, pack, gsettings, is_path, extraVers);
1294 	// Find the unglobbed prefix and iterate from there.
1295 	size_t i = 0;
1296 	size_t sepIdx = 0;
1297 	loop: while (i < res.length) {
1298 		switch_: switch (res[i])
1299 		{
1300 		case '*', '?', '[', '{': break loop;
1301 		case '/': sepIdx = i; goto default;
1302 		default: ++i; break switch_;
1303 		}
1304 	}
1305 	if (i == res.length) //no globbing found in the path
1306 		return [res];
1307 	import std.path : globMatch;
1308 	import std.file : dirEntries, SpanMode;
1309 	return dirEntries(res[0 .. sepIdx], SpanMode.depth)
1310 		.map!(de => de.name)
1311 		.filter!(name => globMatch(name, res))
1312 		.array;
1313 }
1314 /// Expand variables using `$VAR_NAME` or `${VAR_NAME}` syntax.
1315 /// `$$` escapes itself and is expanded to a single `$`.
1316 private string expandVars(alias expandVar)(string s)
1317 {
1318 	import std.functional : not;
1319 
1320 	auto result = appender!string;
1321 
1322 	static bool isVarChar(char c)
1323 	{
1324 		import std.ascii;
1325 		return isAlphaNum(c) || c == '_';
1326 	}
1327 
1328 	while (true)
1329 	{
1330 		auto pos = s.indexOf('$');
1331 		if (pos < 0)
1332 		{
1333 			result.put(s);
1334 			return result.data;
1335 		}
1336 		result.put(s[0 .. pos]);
1337 		s = s[pos + 1 .. $];
1338 		enforce(s.length > 0, "Variable name expected at end of string");
1339 		switch (s[0])
1340 		{
1341 			case '$':
1342 				result.put("$");
1343 				s = s[1 .. $];
1344 				break;
1345 			case '{':
1346 				pos = s.indexOf('}');
1347 				enforce(pos >= 0, "Could not find '}' to match '${'");
1348 				result.put(expandVar(s[1 .. pos]));
1349 				s = s[pos + 1 .. $];
1350 				break;
1351 			default:
1352 				pos = s.representation.countUntil!(not!isVarChar);
1353 				if (pos < 0)
1354 					pos = s.length;
1355 				result.put(expandVar(s[0 .. pos]));
1356 				s = s[pos .. $];
1357 				break;
1358 		}
1359 	}
1360 }
1361 
1362 unittest
1363 {
1364 	string[string] vars =
1365 	[
1366 		"A" : "a",
1367 		"B" : "b",
1368 	];
1369 
1370 	string expandVar(string name) { auto p = name in vars; enforce(p, name); return *p; }
1371 
1372 	assert(expandVars!expandVar("") == "");
1373 	assert(expandVars!expandVar("x") == "x");
1374 	assert(expandVars!expandVar("$$") == "$");
1375 	assert(expandVars!expandVar("x$$") == "x$");
1376 	assert(expandVars!expandVar("$$x") == "$x");
1377 	assert(expandVars!expandVar("$$$$") == "$$");
1378 	assert(expandVars!expandVar("x$A") == "xa");
1379 	assert(expandVars!expandVar("x$$A") == "x$A");
1380 	assert(expandVars!expandVar("$A$B") == "ab");
1381 	assert(expandVars!expandVar("${A}$B") == "ab");
1382 	assert(expandVars!expandVar("$A${B}") == "ab");
1383 	assert(expandVars!expandVar("a${B}") == "ab");
1384 	assert(expandVars!expandVar("${A}b") == "ab");
1385 
1386 	import std.exception : assertThrown;
1387 	assertThrown(expandVars!expandVar("$"));
1388 	assertThrown(expandVars!expandVar("${}"));
1389 	assertThrown(expandVars!expandVar("$|"));
1390 	assertThrown(expandVars!expandVar("x$"));
1391 	assertThrown(expandVars!expandVar("$X"));
1392 	assertThrown(expandVars!expandVar("${"));
1393 	assertThrown(expandVars!expandVar("${X"));
1394 
1395 	// https://github.com/dlang/dmd/pull/9275
1396 	assert(expandVars!expandVar("$${DUB_EXE:-dub}") == "${DUB_EXE:-dub}");
1397 }
1398 
1399 // Keep the following list up-to-date if adding more build settings variables.
1400 /// List of variables that can be used in build settings
1401 package(dub) immutable buildSettingsVars = [
1402 	"ARCH", "PLATFORM", "PLATFORM_POSIX", "BUILD_TYPE"
1403 ];
1404 
1405 private string getVariable(Project, Package)(string name, in Project project, in Package pack, in GeneratorSettings gsettings, in string[string][] extraVars = null)
1406 {
1407 	import dub.internal.utils : getDUBExePath;
1408 	import std.process : environment, escapeShellFileName;
1409 	import std.uni : asUpperCase;
1410 
1411 	NativePath path;
1412 	if (name == "PACKAGE_DIR")
1413 		path = pack.path;
1414 	else if (name == "ROOT_PACKAGE_DIR")
1415 		path = project.rootPackage.path;
1416 
1417 	if (name.endsWith("_PACKAGE_DIR")) {
1418 		auto pname = name[0 .. $-12];
1419 		foreach (prj; project.getTopologicalPackageList())
1420 			if (prj.name.asUpperCase.map!(a => a == '-' ? '_' : a).equal(pname))
1421 			{
1422 				path = prj.path;
1423 				break;
1424 			}
1425 	}
1426 
1427 	if (!path.empty)
1428 	{
1429 		// no trailing slash for clean path concatenation (see #1392)
1430 		path.endsWithSlash = false;
1431 		return path.toNativeString();
1432 	}
1433 
1434 	if (name == "DUB") {
1435 		return getDUBExePath(gsettings.platform.compilerBinary);
1436 	}
1437 
1438 	if (name == "ARCH") {
1439 		foreach (a; gsettings.platform.architecture)
1440 			return a;
1441 		return "";
1442 	}
1443 
1444 	if (name == "PLATFORM") {
1445 		import std.algorithm : filter;
1446 		foreach (p; gsettings.platform.platform.filter!(p => p != "posix"))
1447 			return p;
1448 		foreach (p; gsettings.platform.platform)
1449 			return p;
1450 		return "";
1451 	}
1452 
1453 	if (name == "PLATFORM_POSIX") {
1454 		import std.algorithm : canFind;
1455 		if (gsettings.platform.platform.canFind("posix"))
1456 			return "posix";
1457 		foreach (p; gsettings.platform.platform)
1458 			return p;
1459 		return "";
1460 	}
1461 
1462 	if (name == "BUILD_TYPE") return gsettings.buildType;
1463 
1464 	if (name == "DFLAGS" || name == "LFLAGS")
1465 	{
1466 		auto buildSettings = pack.getBuildSettings(gsettings.platform, gsettings.config);
1467 		if (name == "DFLAGS")
1468 			return join(buildSettings.dflags," ");
1469 		else if (name == "LFLAGS")
1470 			return join(buildSettings.lflags," ");
1471 	}
1472 	
1473 	import std.range;
1474 	foreach (aa; retro(extraVars))
1475 		if (auto exvar = name in aa)
1476 			return *exvar;
1477 
1478 	auto envvar = environment.get(name);
1479 	if (envvar !is null) return envvar;
1480 
1481 	throw new Exception("Invalid variable: "~name);
1482 }
1483 
1484 
1485 unittest
1486 {
1487 	static struct MockPackage
1488 	{
1489 		this(string name)
1490 		{
1491 			this.name = name;
1492 			version (Posix)
1493 				path = NativePath("/pkgs/"~name);
1494 			else version (Windows)
1495 				path = NativePath(`C:\pkgs\`~name);
1496 			// see 4d4017c14c, #268, and #1392 for why this all package paths end on slash internally
1497 			path.endsWithSlash = true;
1498 		}
1499 		string name;
1500 		NativePath path;
1501 		BuildSettings getBuildSettings(in BuildPlatform platform, string config) const
1502 		{
1503 			return BuildSettings();
1504 		}
1505 	}
1506 
1507 	static struct MockProject
1508 	{
1509 		MockPackage rootPackage;
1510 		inout(MockPackage)[] getTopologicalPackageList() inout
1511 		{
1512 			return _dependencies;
1513 		}
1514 	private:
1515 		MockPackage[] _dependencies;
1516 	}
1517 
1518 	MockProject proj = {
1519 		rootPackage: MockPackage("root"),
1520 		_dependencies: [MockPackage("dep1"), MockPackage("dep2")]
1521 	};
1522 	auto pack = MockPackage("test");
1523 	GeneratorSettings gsettings;
1524 	enum isPath = true;
1525 
1526 	import std.path : dirSeparator;
1527 
1528 	static NativePath woSlash(NativePath p) { p.endsWithSlash = false; return p; }
1529 	// basic vars
1530 	assert(processVars("Hello $PACKAGE_DIR", proj, pack, gsettings, !isPath) == "Hello "~woSlash(pack.path).toNativeString);
1531 	assert(processVars("Hello $ROOT_PACKAGE_DIR", proj, pack, gsettings, !isPath) == "Hello "~woSlash(proj.rootPackage.path).toNativeString.chomp(dirSeparator));
1532 	assert(processVars("Hello $DEP1_PACKAGE_DIR", proj, pack, gsettings, !isPath) == "Hello "~woSlash(proj._dependencies[0].path).toNativeString);
1533 	// ${VAR} replacements
1534 	assert(processVars("Hello ${PACKAGE_DIR}"~dirSeparator~"foobar", proj, pack, gsettings, !isPath) == "Hello "~(pack.path ~ "foobar").toNativeString);
1535 	assert(processVars("Hello $PACKAGE_DIR"~dirSeparator~"foobar", proj, pack, gsettings, !isPath) == "Hello "~(pack.path ~ "foobar").toNativeString);
1536 	// test with isPath
1537 	assert(processVars("local", proj, pack, gsettings, isPath) == (pack.path ~ "local").toNativeString);
1538 	assert(processVars("foo/$$ESCAPED", proj, pack, gsettings, isPath) == (pack.path ~ "foo/$ESCAPED").toNativeString);
1539 	assert(processVars("$$ESCAPED", proj, pack, gsettings, !isPath) == "$ESCAPED");
1540 	// test other env variables
1541 	import std.process : environment;
1542 	environment["MY_ENV_VAR"] = "blablabla";
1543 	assert(processVars("$MY_ENV_VAR", proj, pack, gsettings, !isPath) == "blablabla");
1544 	assert(processVars("${MY_ENV_VAR}suffix", proj, pack, gsettings, !isPath) == "blablablasuffix");
1545 	assert(processVars("$MY_ENV_VAR-suffix", proj, pack, gsettings, !isPath) == "blablabla-suffix");
1546 	assert(processVars("$MY_ENV_VAR:suffix", proj, pack, gsettings, !isPath) == "blablabla:suffix");
1547 	assert(processVars("$MY_ENV_VAR$MY_ENV_VAR", proj, pack, gsettings, !isPath) == "blablablablablabla");
1548 	environment.remove("MY_ENV_VAR");
1549 }
1550 
1551 /** Holds and stores a set of version selections for package dependencies.
1552 
1553 	This is the runtime representation of the information contained in
1554 	"dub.selections.json" within a package's directory.
1555 */
1556 final class SelectedVersions {
1557 	private struct Selected {
1558 		Dependency dep;
1559 		//Dependency[string] packages;
1560 	}
1561 	private {
1562 		enum FileVersion = 1;
1563 		Selected[string] m_selections;
1564 		bool m_dirty = false; // has changes since last save
1565 		bool m_bare = true;
1566 	}
1567 
1568 	/// Default file name to use for storing selections.
1569 	enum defaultFile = "dub.selections.json";
1570 
1571 	/// Constructs a new empty version selection.
1572 	this() {}
1573 
1574 	/** Constructs a new version selection from JSON data.
1575 
1576 		The structure of the JSON document must match the contents of the
1577 		"dub.selections.json" file.
1578 	*/
1579 	this(Json data)
1580 	{
1581 		deserialize(data);
1582 		m_dirty = false;
1583 	}
1584 
1585 	/** Constructs a new version selections from an existing JSON file.
1586 	*/
1587 	this(NativePath path)
1588 	{
1589 		auto json = jsonFromFile(path);
1590 		deserialize(json);
1591 		m_dirty = false;
1592 		m_bare = false;
1593 	}
1594 
1595 	/// Returns a list of names for all packages that have a version selection.
1596 	@property string[] selectedPackages() const { return m_selections.keys; }
1597 
1598 	/// Determines if any changes have been made after loading the selections from a file.
1599 	@property bool dirty() const { return m_dirty; }
1600 
1601 	/// Determine if this set of selections is still empty (but not `clear`ed).
1602 	@property bool bare() const { return m_bare && !m_dirty; }
1603 
1604 	/// Removes all selections.
1605 	void clear()
1606 	{
1607 		m_selections = null;
1608 		m_dirty = true;
1609 	}
1610 
1611 	/// Duplicates the set of selected versions from another instance.
1612 	void set(SelectedVersions versions)
1613 	{
1614 		m_selections = versions.m_selections.dup;
1615 		m_dirty = true;
1616 	}
1617 
1618 	/// Selects a certain version for a specific package.
1619 	void selectVersion(string package_id, Version version_)
1620 	{
1621 		if (auto ps = package_id in m_selections) {
1622 			if (ps.dep == Dependency(version_))
1623 				return;
1624 		}
1625 		m_selections[package_id] = Selected(Dependency(version_)/*, issuer*/);
1626 		m_dirty = true;
1627 	}
1628 
1629 	/// Selects a certain path for a specific package.
1630 	void selectVersion(string package_id, NativePath path)
1631 	{
1632 		if (auto ps = package_id in m_selections) {
1633 			if (ps.dep == Dependency(path))
1634 				return;
1635 		}
1636 		m_selections[package_id] = Selected(Dependency(path));
1637 		m_dirty = true;
1638 	}
1639 
1640 	/// Selects a certain Git reference for a specific package.
1641 	void selectVersionWithRepository(string package_id, Repository repository, string spec)
1642 	{
1643 		const dependency = Dependency(repository, spec);
1644 		if (auto ps = package_id in m_selections) {
1645 			if (ps.dep == dependency)
1646 				return;
1647 		}
1648 		m_selections[package_id] = Selected(dependency);
1649 		m_dirty = true;
1650 	}
1651 
1652 	/// Removes the selection for a particular package.
1653 	void deselectVersion(string package_id)
1654 	{
1655 		m_selections.remove(package_id);
1656 		m_dirty = true;
1657 	}
1658 
1659 	/// Determines if a particular package has a selection set.
1660 	bool hasSelectedVersion(string packageId)
1661 	const {
1662 		return (packageId in m_selections) !is null;
1663 	}
1664 
1665 	/** Returns the selection for a particular package.
1666 
1667 		Note that the returned `Dependency` can either have the
1668 		`Dependency.path` property set to a non-empty value, in which case this
1669 		is a path based selection, or its `Dependency.version_` property is
1670 		valid and it is a version selection.
1671 	*/
1672 	Dependency getSelectedVersion(string packageId)
1673 	const {
1674 		enforce(hasSelectedVersion(packageId));
1675 		return m_selections[packageId].dep;
1676 	}
1677 
1678 	/** Stores the selections to disk.
1679 
1680 		The target file will be written in JSON format. Usually, `defaultFile`
1681 		should be used as the file name and the directory should be the root
1682 		directory of the project's root package.
1683 	*/
1684 	void save(NativePath path)
1685 	{
1686 		Json json = serialize();
1687 		auto file = openFile(path, FileMode.createTrunc);
1688 		scope(exit) file.close();
1689 
1690 		assert(json.type == Json.Type.object);
1691 		assert(json.length == 2);
1692 		assert(json["versions"].type != Json.Type.undefined);
1693 
1694 		file.write("{\n\t\"fileVersion\": ");
1695 		file.writeJsonString(json["fileVersion"]);
1696 		file.write(",\n\t\"versions\": {");
1697 		auto vers = json["versions"].get!(Json[string]);
1698 		bool first = true;
1699 		foreach (k; vers.byKey.array.sort()) {
1700 			if (!first) file.write(",");
1701 			else first = false;
1702 			file.write("\n\t\t");
1703 			file.writeJsonString(Json(k));
1704 			file.write(": ");
1705 			file.writeJsonString(vers[k]);
1706 		}
1707 		file.write("\n\t}\n}\n");
1708 		m_dirty = false;
1709 		m_bare = false;
1710 	}
1711 
1712 	static Json dependencyToJson(Dependency d)
1713 	{
1714 		if (!d.repository.empty) {
1715 			return serializeToJson([
1716 				"version": d.version_.toString(),
1717 				"repository": d.repository.toString,
1718 			]);
1719 		} else if (d.path.empty) return Json(d.version_.toString());
1720 		else return serializeToJson(["path": d.path.toString()]);
1721 	}
1722 
1723 	static Dependency dependencyFromJson(Json j)
1724 	{
1725 		if (j.type == Json.Type..string)
1726 			return Dependency(Version(j.get!string));
1727 		else if (j.type == Json.Type.object && "path" in j)
1728 			return Dependency(NativePath(j["path"].get!string));
1729 		else if (j.type == Json.Type.object && "repository" in j)
1730 			return Dependency(Repository(j["repository"].get!string),
1731 				enforce("version" in j, "Expected \"version\" field in repository version object").get!string);
1732 		else throw new Exception(format("Unexpected type for dependency: %s", j));
1733 	}
1734 
1735 	Json serialize()
1736 	const {
1737 		Json json = serializeToJson(m_selections);
1738 		Json serialized = Json.emptyObject;
1739 		serialized["fileVersion"] = FileVersion;
1740 		serialized["versions"] = Json.emptyObject;
1741 		foreach (p, v; m_selections)
1742 			serialized["versions"][p] = dependencyToJson(v.dep);
1743 		return serialized;
1744 	}
1745 
1746 	private void deserialize(Json json)
1747 	{
1748 		enforce(cast(int)json["fileVersion"] == FileVersion, "Mismatched dub.select.json version: " ~ to!string(cast(int)json["fileVersion"]) ~ "vs. " ~to!string(FileVersion));
1749 		clear();
1750 		scope(failure) clear();
1751 		foreach (string p, v; json["versions"])
1752 			m_selections[p] = Selected(dependencyFromJson(v));
1753 	}
1754 }