project/lib/build/ProjectBuilder.js

  1. import {rimraf} from "rimraf";
  2. import * as resourceFactory from "@ui5/fs/resourceFactory";
  3. import BuildLogger from "@ui5/logger/internal/loggers/Build";
  4. import composeProjectList from "./helpers/composeProjectList.js";
  5. import BuildContext from "./helpers/BuildContext.js";
  6. import prettyHrtime from "pretty-hrtime";
  7. import OutputStyleEnum from "./helpers/ProjectBuilderOutputStyle.js";
  9. /**
  10.  * @public
  11.  * @class
  12.  * @alias @ui5/project/build/ProjectBuilder
  13.  */
  14. class ProjectBuilder {
  15. 	#log;
  16. 	/**
  17. 	 * Build Configuration
  18. 	 *
  19. 	 * @public
  20. 	 * @typedef {object} @ui5/project/build/ProjectBuilder~BuildConfiguration
  21. 	 * @property {boolean} [selfContained=false] Flag to activate self contained build
  22. 	 * @property {boolean} [cssVariables=false] Flag to activate CSS variables generation
  23. 	 * @property {boolean} [jsdoc=false] Flag to activate JSDoc build
  24. 	 * @property {boolean} [createBuildManifest=false]
  25. 	 *   Whether to create a build manifest file for the root project.
  26. 	 *   This is currently only supported for projects of type 'library' and 'theme-library'
  27. 	 *   No other dependencies can be included in the build result.
  28. 	 * @property {module:@ui5/project/build/ProjectBuilderOutputStyle} [outputStyle=Default]
  29. 	 *   Processes build results into a specific directory structure.
  30. 	 * @property {Array.<string>} [includedTasks=[]] List of tasks to be included
  31. 	 * @property {Array.<string>} [excludedTasks=[]] List of tasks to be excluded.
  32. 	 * 			If the wildcard '*' is provided, only the included tasks will be executed.
  33. 	 */
  35. 	/**
  36. 	 * As an alternative to providing plain lists of names of dependencies to include and exclude, you can provide a
  37. 	 * more complex "Dependency Includes" object to define which dependencies should be part of the build result.
  38. 	 * <br>
  39. 	 * This information is then used to compile lists of <code>includedDependencies</code> and
  40. 	 * <code>excludedDependencies</code>, which are applied during the build process.
  41. 	 * <br><br>
  42. 	 * Regular expression-parameters are directly applied to a list of all project dependencies
  43. 	 * so that they don't need to be evaluated in later processing steps.
  44. 	 * <br><br>
  45. 	 * Generally, includes are handled with a higher priority than excludes. Additionally, operations for processing
  46. 	 * transitive dependencies are handled with a lower priority than explicitly mentioned dependencies. The "default"
  47. 	 * dependency-includes are appended at the end.
  48. 	 * <br><br>
  49. 	 * The priority of the various dependency lists is applied in the following order.
  50. 	 * Note that a later exclude can't overrule an earlier include.
  51. 	 * <br>
  52. 	 * <ol>
  53. 	 *   <li><code>includeDependency</code>, <code>includeDependencyRegExp</code></li>
  54. 	 *   <li><code>excludeDependency</code>, <code>excludeDependencyRegExp</code></li>
  55. 	 *   <li><code>includeDependencyTree</code></li>
  56. 	 *   <li><code>excludeDependencyTree</code></li>
  57. 	 *   <li><code>defaultIncludeDependency</code>, <code>defaultIncludeDependencyRegExp</code>,
  58. 	 *     <code>defaultIncludeDependencyTree</code></li>
  59. 	 * </ol>
  60. 	 *
  61. 	 * @public
  62. 	 * @typedef {object} @ui5/project/build/ProjectBuilder~DependencyIncludes
  63. 	 * @property {boolean} includeAllDependencies
  64. 	 *   Whether all dependencies should be part of the build result
  65. 	 *	 This parameter has the lowest priority and basically includes all remaining (not excluded) projects as include
  66. 	 * @property {string[]} includeDependency
  67. 	 *   The dependencies to be considered in <code>includedDependencies</code>; the
  68. 	 *   <code>*</code> character can be used as wildcard for all dependencies and
  69. 	 *   is an alias for the CLI option <code>--all</code>
  70. 	 * @property {string[]} includeDependencyRegExp
  71. 	 *   Strings which are interpreted as regular expressions
  72. 	 *   to describe the selection of dependencies to be considered in <code>includedDependencies</code>
  73. 	 * @property {string[]} includeDependencyTree
  74. 	 *   The dependencies to be considered in <code>includedDependencies</code>;
  75. 	 *   transitive dependencies are also appended
  76. 	 * @property {string[]} excludeDependency
  77. 	 *   The dependencies to be considered in <code>excludedDependencies</code>
  78. 	 * @property {string[]} excludeDependencyRegExp
  79. 	 *   Strings which are interpreted as regular expressions
  80. 	 *   to describe the selection of dependencies to be considered in <code>excludedDependencies</code>
  81. 	 * @property {string[]} excludeDependencyTree
  82. 	 *   The dependencies to be considered in <code>excludedDependencies</code>;
  83. 	 *   transitive dependencies are also appended
  84. 	 * @property {string[]} defaultIncludeDependency
  85. 	 *   Same as <code>includeDependency</code> parameter;
  86. 	 *   typically used in project build settings
  87. 	 * @property {string[]} defaultIncludeDependencyRegExp
  88. 	 *   Same as <code>includeDependencyRegExp</code> parameter;
  89. 	 *   typically used in project build settings
  90. 	 * @property {string[]} defaultIncludeDependencyTree
  91. 	 *   Same as <code>includeDependencyTree</code> parameter;
  92. 	 *   typically used in project build settings
  93. 	 */
  95. 	/**
  96. 	 * Executes a project build, including all necessary or requested dependencies
  97. 	 *
  98. 	 * @public
  99. 	 * @param {object} parameters
  100. 	 * @param {@ui5/project/graph/ProjectGraph} parameters.graph Project graph
  101. 	 * @param {@ui5/project/build/ProjectBuilder~BuildConfiguration} [parameters.buildConfig] Build configuration
  102. 	 * @param {@ui5/builder/tasks/taskRepository} parameters.taskRepository Task Repository module to use
  103. 	 */
  104. 	constructor({graph, buildConfig, taskRepository}) {
  105. 		if (!graph) {
  106. 			throw new Error(`Missing parameter 'graph'`);
  107. 		}
  108. 		if (!taskRepository) {
  109. 			throw new Error(`Missing parameter 'taskRepository'`);
  110. 		}
  111. 		if (!graph.isSealed()) {
  112. 			throw new Error(
  113. 				`Can not build project graph with root node ${graph.getRoot().getName()}: Graph is not sealed`);
  114. 		}
  116. 		this._graph = graph;
  117. 		this._buildContext = new BuildContext(graph, taskRepository, buildConfig);
  118. 		this.#log = new BuildLogger("ProjectBuilder");
  119. 	}
  121. 	/**
  122. 	 * Executes a project build, including all necessary or requested dependencies
  123. 	 *
  124. 	 * @public
  125. 	 * @param {object} parameters Parameters
  126. 	 * @param {string} parameters.destPath Target path
  127. 	 * @param {boolean} [parameters.cleanDest=false] Decides whether project should clean the target path before build
  128. 	 * @param {Array.<string|RegExp>} [parameters.includedDependencies=[]]
  129. 	 *   List of names of projects to include in the build result
  130. 	 *   If the wildcard '*' is provided, all dependencies will be included in the build result.
  131. 	 * @param {Array.<string|RegExp>} [parameters.excludedDependencies=[]]
  132. 	 *   List of names of projects to exclude from the build result.
  133. 	 * @param {@ui5/project/build/ProjectBuilder~DependencyIncludes} [parameters.dependencyIncludes]
  134. 	 *   Alternative to the <code>includedDependencies</code> and <code>excludedDependencies</code> parameters.
  135. 	 *   Allows for a more sophisticated configuration for defining which dependencies should be
  136. 	 *   part of the build result. If this is provided, the other mentioned parameters are ignored.
  137. 	 * @returns {Promise} Promise resolving once the build has finished
  138. 	 */
  139. 	async build({
  140. 		destPath, cleanDest = false,
  141. 		includedDependencies = [], excludedDependencies = [],
  142. 		dependencyIncludes
  143. 	}) {
  144. 		if (!destPath) {
  145. 			throw new Error(`Missing parameter 'destPath'`);
  146. 		}
  147. 		if (dependencyIncludes) {
  148. 			if (includedDependencies.length || excludedDependencies.length) {
  149. 				throw new Error(
  150. 					"Parameter 'dependencyIncludes' can't be used in conjunction " +
  151. 					"with parameters 'includedDependencies' or 'excludedDependencies");
  152. 			}
  153. 		}
  154. 		const rootProjectName = this._graph.getRoot().getName();
  155. 		this.#log.info(`Preparing build for project ${rootProjectName}`);
  156. 		this.#log.info(`  Target directory: ${destPath}`);
  158. 		// Get project filter function based on include/exclude params
  159. 		// (also logs some info to console)
  160. 		const filterProject = await this._getProjectFilter({
  161. 			explicitIncludes: includedDependencies,
  162. 			explicitExcludes: excludedDependencies,
  163. 			dependencyIncludes
  164. 		});
  166. 		// Count total number of projects to build based on input
  167. 		const requestedProjects = this._graph.getProjectNames().filter(function(projectName) {
  168. 			return filterProject(projectName);
  169. 		});
  171. 		if (requestedProjects.length > 1) {
  172. 			const {createBuildManifest} = this._buildContext.getBuildConfig();
  173. 			if (createBuildManifest) {
  174. 				throw new Error(
  175. 					`It is currently not supported to request the creation of a build manifest ` +
  176. 					`while including any dependencies into the build result`);
  177. 			}
  178. 		}
  180. 		const projectBuildContexts = await this._createRequiredBuildContexts(requestedProjects);
  181. 		const cleanupSigHooks = this._registerCleanupSigHooks();
  182. 		const fsTarget = resourceFactory.createAdapter({
  183. 			fsBasePath: destPath,
  184. 			virBasePath: "/"
  185. 		});
  187. 		const queue = [];
  188. 		const alreadyBuilt = [];
  190. 		// Create build queue based on graph depth-first search to ensure correct build order
  191. 		await this._graph.traverseDepthFirst(async ({project}) => {
  192. 			const projectName = project.getName();
  193. 			const projectBuildContext = projectBuildContexts.get(projectName);
  194. 			if (projectBuildContext) {
  195. 				// Build context exists
  196. 				//	=> This project needs to be built or, in case it has already
  197. 				//		been built, it's build result needs to be written out (if requested)
  198. 				queue.push(projectBuildContext);
  199. 				if (!projectBuildContext.requiresBuild()) {
  200. 					alreadyBuilt.push(projectName);
  201. 				}
  202. 			}
  203. 		});
  205. 		this.#log.setProjects(queue.map((projectBuildContext) => {
  206. 			return projectBuildContext.getProject().getName();
  207. 		}));
  208. 		if (queue.length > 1) { // Do not log if only the root project is being built
  209. 			this.#log.info(`Processing ${queue.length} projects`);
  210. 			if (alreadyBuilt.length) {
  211. 				this.#log.info(`  Reusing build results of ${alreadyBuilt.length} projects`);
  212. 				this.#log.info(`  Building ${queue.length - alreadyBuilt.length} projects`);
  213. 			}
  215. 			if (this.#log.isLevelEnabled("verbose")) {
  216. 				this.#log.verbose(`  Required projects:`);
  217. 				this.#log.verbose(`    ${queue
  218. 					.map((projectBuildContext) => {
  219. 						const projectName = projectBuildContext.getProject().getName();
  220. 						let msg;
  221. 						if (alreadyBuilt.includes(projectName)) {
  222. 							const buildMetadata = projectBuildContext.getBuildMetadata();
  223. 							const ts = new Date(buildMetadata.timestamp).toUTCString();
  224. 							msg = `*> ${projectName} /// already built at ${ts}`;
  225. 						} else {
  226. 							msg = `=> ${projectName}`;
  227. 						}
  228. 						return msg;
  229. 					})
  230. 					.join("\n    ")}`);
  231. 			}
  232. 		}
  234. 		if (cleanDest) {
  235. 			this.#log.info(`Cleaning target directory...`);
  236. 			await rimraf(destPath);
  237. 		}
  238. 		const startTime = process.hrtime();
  239. 		try {
  240. 			const pWrites = [];
  241. 			for (const projectBuildContext of queue) {
  242. 				const projectName = projectBuildContext.getProject().getName();
  243. 				const projectType = projectBuildContext.getProject().getType();
  244. 				this.#log.verbose(`Processing project ${projectName}...`);
  246. 				// Only build projects that are not already build (i.e. provide a matching build manifest)
  247. 				if (alreadyBuilt.includes(projectName)) {
  248. 					this.#log.skipProjectBuild(projectName, projectType);
  249. 				} else {
  250. 					this.#log.startProjectBuild(projectName, projectType);
  251. 					await projectBuildContext.getTaskRunner().runTasks();
  252. 					this.#log.endProjectBuild(projectName, projectType);
  253. 				}
  254. 				if (!requestedProjects.includes(projectName)) {
  255. 					// Project has not been requested
  256. 					//	=> Its resources shall not be part of the build result
  257. 					continue;
  258. 				}
  260. 				this.#log.verbose(`Writing out files...`);
  261. 				pWrites.push(this._writeResults(projectBuildContext, fsTarget));
  262. 			}
  263. 			await Promise.all(pWrites);
  264. 			this.#log.info(`Build succeeded in ${this._getElapsedTime(startTime)}`);
  265. 		} catch (err) {
  266. 			this.#log.error(`Build failed in ${this._getElapsedTime(startTime)}`);
  267. 			throw err;
  268. 		} finally {
  269. 			this._deregisterCleanupSigHooks(cleanupSigHooks);
  270. 			await this._executeCleanupTasks();
  271. 		}
  272. 	}
  274. 	async _createRequiredBuildContexts(requestedProjects) {
  275. 		const requiredProjects = new Set(this._graph.getProjectNames().filter((projectName) => {
  276. 			return requestedProjects.includes(projectName);
  277. 		}));
  279. 		const projectBuildContexts = new Map();
  281. 		for (const projectName of requiredProjects) {
  282. 			this.#log.verbose(`Creating build context for project ${projectName}...`);
  283. 			const projectBuildContext = this._buildContext.createProjectContext({
  284. 				project: this._graph.getProject(projectName)
  285. 			});
  287. 			projectBuildContexts.set(projectName, projectBuildContext);
  289. 			if (projectBuildContext.requiresBuild()) {
  290. 				const taskRunner = projectBuildContext.getTaskRunner();
  291. 				const requiredDependencies = await taskRunner.getRequiredDependencies();
  293. 				if (requiredDependencies.size === 0) {
  294. 					continue;
  295. 				}
  296. 				// This project needs to be built and required dependencies to be built as well
  297. 				this._graph.getDependencies(projectName).forEach((depName) => {
  298. 					if (projectBuildContexts.has(depName)) {
  299. 						// Build context already exists
  300. 						//	=> Dependency will be built
  301. 						return;
  302. 					}
  303. 					if (!requiredDependencies.has(depName)) {
  304. 						return;
  305. 					}
  306. 					// Add dependency to list of projects to build
  307. 					requiredProjects.add(depName);
  308. 				});
  309. 			}
  310. 		}
  312. 		return projectBuildContexts;
  313. 	}
  315. 	async _getProjectFilter({
  316. 		dependencyIncludes,
  317. 		explicitIncludes,
  318. 		explicitExcludes
  319. 	}) {
  320. 		const {includedDependencies, excludedDependencies} = await composeProjectList(
  321. 			this._graph,
  322. 			dependencyIncludes || {
  323. 				includeDependencyTree: explicitIncludes,
  324. 				excludeDependencyTree: explicitExcludes
  325. 			}
  326. 		);
  328. 		if (includedDependencies.length) {
  329. 			if (includedDependencies.length === this._graph.getSize() - 1) {
  330. 				this.#log.info(`  Including all dependencies`);
  331. 			} else {
  332. 				this.#log.info(`  Requested dependencies:`);
  333. 				this.#log.info(`    + ${includedDependencies.join("\n    + ")}`);
  334. 			}
  335. 		}
  336. 		if (excludedDependencies.length) {
  337. 			this.#log.info(`  Excluded dependencies:`);
  338. 			this.#log.info(`    - ${excludedDependencies.join("\n    + ")}`);
  339. 		}
  341. 		const rootProjectName = this._graph.getRoot().getName();
  342. 		return function projectFilter(projectName) {
  343. 			function projectMatchesAny(deps) {
  344. 				return deps.some((dep) => dep instanceof RegExp ?
  345. 					dep.test(projectName) : dep === projectName);
  346. 			}
  348. 			if (projectName === rootProjectName) {
  349. 				// Always include the root project
  350. 				return true;
  351. 			}
  353. 			if (projectMatchesAny(excludedDependencies)) {
  354. 				return false;
  355. 			}
  357. 			if (includedDependencies.includes("*") || projectMatchesAny(includedDependencies)) {
  358. 				return true;
  359. 			}
  361. 			return false;
  362. 		};
  363. 	}
  365. 	async _writeResults(projectBuildContext, target) {
  366. 		const project = projectBuildContext.getProject();
  367. 		const taskUtil = projectBuildContext.getTaskUtil();
  368. 		const buildConfig = this._buildContext.getBuildConfig();
  369. 		const {createBuildManifest, outputStyle} = buildConfig;
  370. 		// Output styles are applied only for the root project
  371. 		const isRootProject = taskUtil.isRootProject();
  373. 		let readerStyle = "dist";
  374. 		if (createBuildManifest ||
  375. 			(isRootProject && outputStyle === OutputStyleEnum.Namespace && project.getType() === "application")) {
  376. 			// Ensure buildtime (=namespaced) style when writing with a build manifest or when explicitly requested
  377. 			readerStyle = "buildtime";
  378. 		} else if (isRootProject && outputStyle === OutputStyleEnum.Flat) {
  379. 			readerStyle = "flat";
  380. 		}
  382. 		const reader = project.getReader({
  383. 			style: readerStyle
  384. 		});
  385. 		const resources = await reader.byGlob("/**/*");
  387. 		if (createBuildManifest) {
  388. 			// Create and write a build manifest metadata file
  389. 			const {
  390. 				default: createBuildManifest
  391. 			} = await import("./helpers/createBuildManifest.js");
  392. 			const metadata = await createBuildManifest(project, buildConfig, this._buildContext.getTaskRepository());
  393. 			await target.write(resourceFactory.createResource({
  394. 				path: `/.ui5/build-manifest.json`,
  395. 				string: JSON.stringify(metadata, null, "\t")
  396. 			}));
  397. 		}
  399. 		await Promise.all(resources.map((resource) => {
  400. 			if (taskUtil.getTag(resource, taskUtil.STANDARD_TAGS.OmitFromBuildResult)) {
  401. 				this.#log.silly(`Skipping write of resource tagged as "OmitFromBuildResult": ` +
  402. 					resource.getPath());
  403. 				return; // Skip target write for this resource
  404. 			}
  405. 			return target.write(resource);
  406. 		}));
  408. 		if (isRootProject &&
  409. 			outputStyle === OutputStyleEnum.Flat &&
  410. 			project.getType() !== "application" /* application type is with a default flat build output structure */) {
  411. 			const namespace = project.getNamespace();
  412. 			const libraryResourcesPrefix = `/resources/${namespace}/`;
  413. 			const testResourcesPrefix = "/test-resources/";
  414. 			const namespacedRegex = new RegExp(`/(resources|test-resources)/${namespace}`);
  415. 			const processedResourcesSet = resources.reduce((acc, resource) => acc.add(resource.getPath()), new Set());
  417. 			// If outputStyle === "Flat", then the FlatReader would have filtered
  418. 			// some resources. We now need to get all of the available resources and
  419. 			// do an intersection with the processed/bundled ones.
  420. 			const defaultReader = project.getReader();
  421. 			const defaultResources = await defaultReader.byGlob("/**/*");
  422. 			const flatDefaultResources = defaultResources.map((resource) => ({
  423. 				flatResource: resource.getPath().replace(namespacedRegex, ""),
  424. 				originalPath: resource.getPath(),
  425. 			}));
  427. 			const skippedResources = flatDefaultResources.filter((resource) => {
  428. 				return processedResourcesSet.has(resource.flatResource) === false;
  429. 			});
  431. 			skippedResources.forEach((resource) => {
  432. 				if (resource.originalPath.startsWith(testResourcesPrefix)) {
  433. 					this.#log.verbose(
  434. 						`Omitting ${resource.originalPath} from build result. File is part of ${testResourcesPrefix}.`
  435. 					);
  436. 				} else if (!resource.originalPath.startsWith(libraryResourcesPrefix)) {
  437. 					this.#log.warn(
  438. 						`Omitting ${resource.originalPath} from build result. ` +
  439. 							`File is not within project namespace '${namespace}'.`
  440. 					);
  441. 				}
  442. 			});
  443. 		}
  444. 	}
  446. 	async _executeCleanupTasks(force) {
  447. 		this.#log.info("Executing cleanup tasks...");
  449. 		await this._buildContext.executeCleanupTasks(force);
  450. 	}
  452. 	_registerCleanupSigHooks() {
  453. 		const that = this;
  454. 		function createListener(exitCode) {
  455. 			return function() {
  456. 				// Asynchronously cleanup resources, then exit
  457. 				that._executeCleanupTasks(true).then(() => {
  458. 					process.exit(exitCode);
  459. 				});
  460. 			};
  461. 		}
  463. 		const processSignals = {
  464. 			"SIGHUP": createListener(128 + 1),
  465. 			"SIGINT": createListener(128 + 2),
  466. 			"SIGTERM": createListener(128 + 15),
  467. 			"SIGBREAK": createListener(128 + 21)
  468. 		};
  470. 		for (const signal of Object.keys(processSignals)) {
  471. 			process.on(signal, processSignals[signal]);
  472. 		}
  474. 		// TODO: Also cleanup for unhandled rejections and exceptions?
  475. 		// Add additional events like signals since they are registered on the process
  476. 		//	event emitter in a similar fashion
  477. 		// processSignals["unhandledRejection"] = createListener(1);
  478. 		// process.once("unhandledRejection", processSignals["unhandledRejection"]);
  479. 		// processSignals["uncaughtException"] = function(err, origin) {
  480. 		// 	const fs = require("fs");
  481. 		// 	fs.writeSync(
  482. 		// 		process.stderr.fd,
  483. 		// 		`Caught exception: ${err}\n` +
  484. 		// 		`Exception origin: ${origin}`
  485. 		// 	);
  486. 		// 	createListener(1)();
  487. 		// };
  488. 		// process.once("uncaughtException", processSignals["uncaughtException"]);
  490. 		return processSignals;
  491. 	}
  493. 	_deregisterCleanupSigHooks(signals) {
  494. 		for (const signal of Object.keys(signals)) {
  495. 			process.removeListener(signal, signals[signal]);
  496. 		}
  497. 	}
  499. 	/**
  500. 	 * Calculates the elapsed build time and returns a prettified output
  501. 	 *
  502. 	 * @private
  503. 	 * @param {Array} startTime Array provided by <code>process.hrtime()</code>
  504. 	 * @returns {string} Difference between now and the provided time array as formatted string
  505. 	 */
  506. 	_getElapsedTime(startTime) {
  507. 		const timeDiff = process.hrtime(startTime);
  508. 		return prettyHrtime(timeDiff);
  509. 	}
  510. }
  512. export default ProjectBuilder;