From e0df7db79b81544d345cdf7f8542229d218a9403 Mon Sep 17 00:00:00 2001 From: katunin-ng Date: Wed, 22 May 2019 15:38:37 +0300 Subject: [PATCH] updated after UA review --- README.md | 10 +++++----- docs/docs/configuration.md | 10 +++++----- docs/docs/migration.md | 18 +++++++++++------- docs/docs/performance.md | 2 +- docs/docs/usage.md | 3 ++- 5 files changed, 24 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index 4a77f0b9a..488157baa 100644 --- a/README.md +++ b/README.md @@ -12,20 +12,20 @@ #### Multi-Target Application -Before using this package, be sure you are familiar with the multi-target application concept and terminology. For background and detailed information, see the [Multi-Target Application Model](https://www.sap.com/documents/2016/06/e2f618e4-757c-0010-82c7-eda71af511fa.html) guide. +Before using this package, make sure that you are familiar with the multi-target application concept and terminology. For background and detailed information, see the [Multi-Target Application Model](https://www.sap.com/documents/2016/06/e2f618e4-757c-0010-82c7-eda71af511fa.html) guide. #### The Cloud MTA Build Tool overview The Cloud MTA Build Tool is a standalone command-line tool that builds a deployment-ready -multi-target application (MTA) archive `.mtar` file from the artifacts of an MTA project according to the project’s MTA -development descriptor (`mta.yaml` file) or from module build artifacts according to the MTA deployment descriptor (`mtad.yaml` file). Also it provides commands for runing intermediate build process steps, for example, the mta.yaml file validations,building a single module according to configurations in the development descriptor, generating deployment descriptor, etc. +multitarget application (MTA) archive `.mtar` file from the artifacts of an MTA project according to the project’s MTA +development descriptor (`mta.yaml` file) or from module build artifacts according to the MTA deployment descriptor (`mtad.yaml` file). Also, it provides commands for running intermediate build process steps; for example, the `mta.yaml` file validations, building a single module according to the configurations in the development descriptor, generating the deployment descriptor, and so on. ->For more information, see the the [Cloud MTA Build Tool user guide](https://sap.github.io/cloud-mta-build-tool/) +>For more information, see the [Cloud MTA Build Tool user guide](https://sap.github.io/cloud-mta-build-tool/) ## Contributions Contributions are greatly appreciated. -If you want to contribute, please follow [the guidelines](docs/docs/process.md). +If you want to contribute, follow [the guidelines](docs/docs/process.md). ## Support diff --git a/docs/docs/configuration.md b/docs/docs/configuration.md index b15f1d506..ffc17f1c2 100644 --- a/docs/docs/configuration.md +++ b/docs/docs/configuration.md @@ -26,7 +26,7 @@ To use a non-default builder for a module, specify its name in the builder param #### Configuring build order You can define the dependencies between modules to ensure that they are built in a certain order. In addition, you can use the build results of one module to build another module. -Also you can can configure a build step that is performed before building any of the modules. +Also you can can configure build steps that are performed before building any of the modules. ##### Defining module build order To define the build order of modules, in the `mta.yaml` file, add a `requires` section under the `build-parameters` section of the dependent module; that is, a module that should be built only after building another required module. Then specify the required module name as a property of the dependent module’s `requires` section. @@ -60,7 +60,7 @@ modules: > **_CAUTION:_** Cyclical dependencies are not allowed. If such dependencies are found, the build fails.
-##### Using build results for building another `modulecopy` artifact +##### Using build results for building another module If you want to use the build results of module B for building module A, modify the `requires` section as follows: @@ -91,7 +91,7 @@ modules: #### Configuring a global build -If you want to run a builder process before running builders of the specific modules, define it by using the `build-parameters` section at the global level in the `mta.yaml` file as follows: +If you want to run addtional build steps before running builders of the specific modules, define it by using the `build-parameters` section at global level in the `mta.yaml` file as follows: ```yaml @@ -132,7 +132,7 @@ modules: ... ``` -> **_NOTE:_** Only the following build parameters are considered when configuring a builder at the "before-all" level:
  • `timeout`
  • `commands` (for the `custom` builder only)
  • `fetcher-opts` (for the `fetcher` builder only) +> **_NOTE:_** Only the following build parameters are considered when configuring a builder at the global level:
  • `timeout`
  • `commands` (for the `custom` builder only)
  • `fetcher-opts` (for the `fetcher` builder only)
    #### Configuring the `fetcher` builder @@ -202,7 +202,7 @@ For example: #### Configuring and packaging modules according to target platforms -If you want to control which modules should be packaged into a multitarget application archive for a specific platform during a multitarget application build, use the `supported-platforms` build parameter as follows: +If you want to control which modules should be packaged into a multitarget application archive for a specific platform, use the `supported-platforms` build parameter as follows: ```yaml diff --git a/docs/docs/migration.md b/docs/docs/migration.md index 3d77fff51..2cb6b6fcf 100644 --- a/docs/docs/migration.md +++ b/docs/docs/migration.md @@ -2,11 +2,14 @@ If you have previously used the [Multitarget Application Archive Builder](https://help.sap.com/viewer/58746c584026430a890170ac4d87d03b/Cloud/en-US/ba7dd5a47b7a4858a652d15f9673c28d.html) for building your MTA projects, you should be aware of the differences between the tools. -#### Features that handled differently in the Cloud MTA Build Tool +#### Features that are handled differently in the Cloud MTA Build Tool -* For building an MTA project, the Cloud MTA build Tool uses `GNU Make` technology. Therefore, you should have `GNU Make` installed in your build environmnet. Please read the correponding sections for more information about [`GNU Make` installation](makefile.md) and [commands for building a project](usage.md#how-to-build-an-mta-archive-from-the-project-sources). +
  • The Cloud MTA build Tool uses `GNU Make` technology for building an MTA project. Therefore, you should have `GNU Make` installed in your build environmnet. + +For more information, see sections [`GNU Make` installation](makefile.md) and [commands for building a project](usage.md#how-to-build-an-mta-archive-from-the-project-sources).   -* Packaging of HTML5 modules in `deploy_mode=html5-repo` + +
  • Packaging of HTML5 modules in `deploy_mode=html5-repo` You need to update your `mta.yaml` file to exclude `html5` modules from the resulting MTA archive. In order to do that, add the following to the `build-parameters` section for each module of this type: ```yaml @@ -15,15 +18,16 @@ You need to update your `mta.yaml` file to exclude `html5` modules from the resu supported-platforms: [] ```        For more information about the `supported-platforms` build parameter, see [Configuring and Packaging Modules According to Target Platforms](configuration.md#configuring-and-packaging-modules-according-to-target-platforms). -  -* The following `build-parameters` are not supported by the Cloud MTA Build Tool: +   + +
  • The following `build-parameters` are not supported by the Cloud MTA Build Tool: - If you need to change the default build behavior defined for the correponding builder, see [configure `custom` builder](configuration.md#configuring-the-custom-builder). For a complete list of available builders and their default behaviors, see [Builders execution commands](https://github.com/SAP/cloud-mta-build-tool/blob/master/configs/builder_type_cfg.yaml). + If you need to change the default build behavior defined for the corresponding builder, see [configure `custom` builder](configuration.md#configuring-the-custom-builder). For a complete list of available builders and their default behaviors, see [Builders execution commands](https://github.com/SAP/cloud-mta-build-tool/blob/master/configs/builder_type_cfg.yaml).   #### New features in the Cloud MTA Build Tool -* In addition to configuring build behaviour in `mta.yaml`, you can configure build process of the specific module or the whole project in the `Makefile.mta` file that you can generate the file using [`mbt init` command](usage.md#cloud-mta-build-tool-commands). The generated file contains default configurations for buidling MTA project according to our best practices. +* In addition to configuring the build behaviour in `mta.yaml`, you can configure build process of the specific module or the whole project in the `Makefile.mta` file, which you can generate the file using [`mbt init` command](usage.md#cloud-mta-build-tool-commands). The generated file contains the default configurations for buidling the MTA project according to our best practices.    * If you want to run a builder process before running builders of the specific modules, define it using [global `before-all` build parameters](configuration.md#configuring-global-build).   diff --git a/docs/docs/performance.md b/docs/docs/performance.md index 98e3e5c94..d248ad6cf 100644 --- a/docs/docs/performance.md +++ b/docs/docs/performance.md @@ -1,3 +1,3 @@ -TBD \ No newline at end of file +Under construction \ No newline at end of file diff --git a/docs/docs/usage.md b/docs/docs/usage.md index 101bd98b0..7705ebda5 100644 --- a/docs/docs/usage.md +++ b/docs/docs/usage.md @@ -37,7 +37,7 @@ make -f Makefile.mta p=cf | Command | Usage                          | Description | ------ | -------- | ---------- -| init | `mbt init ` | Generates the `Makefile.mta` file according to the MTA descriptor (`mta.yaml` file).
    The `make` command uses the generated `Makefile.mta` file to package the MTA project.
    Use the `mbt init` command with the following flags:
    • `-s (--source)` is the path to the MTA project; the current path is set as the default.
      Example: `mbt init -s C:/TestProject`
    • `-t (--target)` is the path to the generated `Makefile` folder; the current path is set as the default.
      Example: `mbt init -t C:/TestFolder`
    • `-m (--mode)` is the mode of the `Makefile` generation; supported values are `default` and `verbose`.
      Example: `mbt init -m default` +| init | `mbt init ` | Generates the `Makefile.mta` file according to the MTA descriptor (`mta.yaml` file).
      The `make` command uses the generated `Makefile.mta` file to package the MTA project.
      Use the `mbt init` command with the following flags:
      • `-s (--source)` is the path to the MTA project; the current path is set as the default.
        Example: `mbt init -s C:/TestProject`
      • `-t (--target)` is the path to the generated `Makefile` folder; the current path is set as the default.
        Example: `mbt init -t C:/TestFolder`
        #### Make commands @@ -53,6 +53,7 @@ Use the `make` command to package the MTA project with the following parameters: | Parameter | Type | Mandatory /
        Optional | Description                                                           | Examples | ----------- | ------ | ------- | ---------- | -------------------------------------- +| `-f ` | string | Mandatory | The path to the Makefile.mta file that contains build configurations | `make -f Makefile.mta p=cf` | `p` | string | Mandatory | The name of the deployment platform.
        The supported deployment platforms are:
        • `cf` for SAP Cloud Platform Cloud Foundry environment
        • `neo` for the SAP Cloud Platform Neo environment
        • `xsa` for the SAP HANA XS advanced model |`make -f Makefile.mta p=cf` | `t` | string | Optional | The folder for the generated `MTAR` file. The default value is the current folder. If this parameter is not provided, the `MTAR` file is saved in the `mta_archives` subfolder of the current folder. If the parameter is provided, the `MTAR` file is saved in the root of the folder provided by the argument. | `make -f Makefile.mta p=cf t=C:\temp` | `mtar` | string | Optional | The file name of the generated archive file. If this parameter is omitted, the file name is created according to the following naming convention:

          `_.mtar`

          If the parameter is provided, but does not include an extension, the `.mtar` extension is added. | `make -f Makefile.mta p=cf mtar=myMta`

          `make -f Makefile.mta p=cf mtar=myMta.mtar`