From 92d0cd2b2108a3ede58de1cab6c9e89cff0d5752 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Tue, 28 Aug 2018 13:34:53 +0200 Subject: [PATCH 1/3] [RFC] 0004 Simple Build Extensibility --- rfcs/0004-simple-build-extensibility.md | 158 ++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 rfcs/0004-simple-build-extensibility.md diff --git a/rfcs/0004-simple-build-extensibility.md b/rfcs/0004-simple-build-extensibility.md new file mode 100644 index 0000000000..d469888ab1 --- /dev/null +++ b/rfcs/0004-simple-build-extensibility.md @@ -0,0 +1,158 @@ +- Start Date: 2018-08-28 +- RFC PR: [#](https://github.com/SAP/ui5-tooling/pull/) +- Issue: - +- Affected components + + [x] [ui5-builder](https://github.com/SAP/ui5-builder) + + [ ] [ui5-server](https://github.com/SAP/ui5-server) + + [ ] [ui5-cli](https://github.com/SAP/ui5-cli) + + [ ] [ui5-fs](https://github.com/SAP/ui5-fs) + + [x] [ui5-project](https://github.com/SAP/ui5-project) + + [ ] [ui5-logger](https://github.com/SAP/ui5-logger) + +# RFC 0004 Simple Build Extensibility +## Summary +Add a feature for basic customization of how a single UI5 project is being built. + +## Motivation +Currently the UI5 build is only capable of building UI5 projects of types "application" and "library" with a fixed set of tasks to be executed. + +A UI5 project (for example a library) may want to add build steps. For this, an extensibility mechanism is needed. + +While multiple UI5 projects may require the same kind of "customized" build, easy reuse capabilities are not in focus of this RFC. [RFC 0001](https://github.com/SAP/ui5-tooling/pull/4) focuses more on that. + +This shall be a preliminary solution to allow for basic extensibility and to learn about the different needs and use cases in that area before proceeding with [RFC 0001](https://github.com/SAP/ui5-tooling/pull/4) or similar concepts. + +## Detailed design +### Configuration +In a projects `ui5.yaml`, a new configuration option should be added to define additional tasks that shall be executed at a specific time during the build process of a project. This configuration shall only affect the project it belongs to. The build process of any of the other projects (e.g. project dependencies) shall be unaffected by this configuration. + +A task may require certain tasks to be executed before and after it. This shall be configurable in a simple but less generic way. See [RFC 0001](https://github.com/SAP/ui5-tooling/pull/4) for a concept of a more generic handling. + +A project configuration might look like this: +```yaml +specVersion: "0.1" +type: library +metadata: + name: my.library +builder: + customTasks: + - name: babel + beforeTask: generateComponentPreload + - name: generateMarkdownFiles + afterTask: uglify + configuration: + color: blue +``` + +When building "my.library", this will execute the custom task *babel* before the "standard" task *generateComponentPreload* and *generateMarkdownFiles* after *uglify*. This means that for example *generateComponentPreload* and all following tasks can work with the resources created or modified by the *babel* task. + +### Generic handling of extension +**This section is partially equal to what is outlined in [RFC 0001](https://github.com/SAP/ui5-tooling/blob/rfc-type-ext/rfcs/0001-type-extensibility.md#generic-handling-of-extension).** + +Custom task implementations have similar characteristics than other possible "extensions" of the UI5 Build and Development Tooling. Examples for other extensions include "Shims" (see RFC 0002), server middlewares and translators. + +Therefore a somewhat generic concept for dealing with extensions is needed. + +To separate "UI5 Projects" (i.e. things that represent UI5-artifacts for the browser) from tooling specific things like "extensions", an additional attribute "kind" is added to the ui5.yaml. + +A custom task (a.k.a. "task extension") will consist of at least a ui5.yaml defining it as an extension and a JavaScript implementation. + +#### Example task extension +**`ui5.yaml`**: +```yaml +specVersion: "0.1" +kind: extension +type: task +metadata: + name: generateMarkdownFiles +task: + path: generateMarkdownFiles.js +``` + +**`generateMarkdownFiles.js`**: +```js +const markdownGenerator = require("./markdownGenerator"); + +module.exports = function({workspace, options}) { + return workspace.byGlob("**/*.txt") + .then((textResources) => { + return markdownGenerator({ + resources: textResources + }); + }) + .then((markdownResources) => { + return Promise.all(markdownResources.map((resource) => { + return workspace.write(resource); + })); + }); +}; +``` + +#### Collecting and applying task extensions +A task extension might be a standalone module or part of a project. + +If the extension is part of a project, the single `ui5.yaml` for the above example might look like this: + +```yaml +specVersion: "0.1" +kind: project +type: library +metadata: + name: my.library +builder: + customTasks: + - name: generateMarkdownFiles + afterTask: uglify + configuration: + color: blue +---- +specVersion: "0.1" +kind: extension +type: task +metadata: + name: generateMarkdownFiles +task: + path: generateMarkdownFiles.js +``` + +In this case the extension is no dependency of any kind but automatically collected and processed with the processing of the project. + +The AbstractBuilder will detect the custom task configuration of the project my.library and inject the tasks into the build execution. + + +### Task implementation +A custom task implementation needs to return a function with the following signature (written in JSDoc): + +```js +/** + * Custom task example + * + * @param {Object} parameters Parameters + * @param {DuplexCollection} parameters.workspace DuplexCollection to read and write files + * @param {AbstractReader} parameters.dependencies Reader or Collection to read dependency files + * @param {Object} parameters.options Options + * @param {string} parameters.options.projectName Project name + * @param {string} [parameters.options.configuration] Task configuration if given in ui5.yaml + * @returns {Promise} Promise resolving with undefined once data has been written + */ +module.exports = function({workspace, options}) { + // [...] +}; +``` + +## How we teach this +- Documentation about how to implement custom tasks +- Explanation of the task/processor concept + +## Drawbacks +Custom task configurations might break with future changes to the Application- and LibraryBuilder due to renaming or reordering of the standard tasks. + +## Alternatives +There are ways to consume (and thereby possibly adapt) the existing tooling through its API via taskrunners such as grunt or gulp, or using a custom node.js script. But this offers only limited possibilities, especially when it comes to building transient dependencies. + +[RFC 0001](https://github.com/SAP/ui5-tooling/pull/4) may offer a more generic way to tackle this but requires additional concept and evaluation work. This RFC (0004) should not prevent the implementation of RFC 0001 in the future. + +## Unresolved questions +- Detailed task signature + + Should the whole `project` object be handed over to custom tasks? + From 8122441e9545a50a9efcb7ba2cc08c6df54f0a06 Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Tue, 28 Aug 2018 13:37:08 +0200 Subject: [PATCH 2/3] Add PR link --- rfcs/0004-simple-build-extensibility.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0004-simple-build-extensibility.md b/rfcs/0004-simple-build-extensibility.md index d469888ab1..25ef2b3a59 100644 --- a/rfcs/0004-simple-build-extensibility.md +++ b/rfcs/0004-simple-build-extensibility.md @@ -1,5 +1,5 @@ - Start Date: 2018-08-28 -- RFC PR: [#](https://github.com/SAP/ui5-tooling/pull/) +- RFC PR: [#54](https://github.com/SAP/ui5-tooling/pull/54) - Issue: - - Affected components + [x] [ui5-builder](https://github.com/SAP/ui5-builder) From 9b34c74e9fe21ac0ec004861f48451f4d7a026dd Mon Sep 17 00:00:00 2001 From: Merlin Beutlberger Date: Fri, 16 Nov 2018 14:20:48 +0100 Subject: [PATCH 3/3] Fix yaml and move task implementation into sub-directory Having custom taks in dedicated directories might be the more common approach --- rfcs/0004-simple-build-extensibility.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/rfcs/0004-simple-build-extensibility.md b/rfcs/0004-simple-build-extensibility.md index 25ef2b3a59..f3bfe31d3d 100644 --- a/rfcs/0004-simple-build-extensibility.md +++ b/rfcs/0004-simple-build-extensibility.md @@ -66,10 +66,10 @@ type: task metadata: name: generateMarkdownFiles task: - path: generateMarkdownFiles.js + path: lib/tasks/generateMarkdownFiles.js ``` -**`generateMarkdownFiles.js`**: +**`lib/tasks/generateMarkdownFiles.js`**: ```js const markdownGenerator = require("./markdownGenerator"); @@ -105,14 +105,14 @@ builder: afterTask: uglify configuration: color: blue ----- +--- specVersion: "0.1" kind: extension type: task metadata: name: generateMarkdownFiles task: - path: generateMarkdownFiles.js + path: lib/tasks/generateMarkdownFiles.js ``` In this case the extension is no dependency of any kind but automatically collected and processed with the processing of the project.