@abaplint/transpiler-cli

Transpiler CLI

Examples

Call abap_transpile on the command line, see example in

https://github.com/larshp/abap-advent-2020/blob/main/package.json#L8

Shared factory functions for repeated composite type constructors are enabled by default. Each factory call creates a fresh ABAP value. To preserve inline constructor output, set options.sharedTypeFactories to false in abap_transpile.json:

{
  "options": {
    "sharedTypeFactories": false
  }
}

Omit the option or set it to true to use shared factories.

Output layout

The CLI writes generated project files into output_folder/project/. All input_folder entries belong to the same project, including an array of source folders. Original ABAP sources stay in their input directories.

Each ABAP library gets its own folder under output_folder. The folder name is the repository basename from url (without a trailing slash or .git), or the basename of folder for a local-only library. Set libs[].name to override it:

{
  "input_folder": ["src", "extra"],
  "output_folder": "output",
  "incremental_output": true,
  "libs": [
    {"url": "https://github.com/open-abap/open-abap-core"},
    {"folder": "./deps/utilities", "name": "utilities"}
  ],
  "write_unit_tests": true,
  "write_source_map": true,
  "options": {"addCommonJS": true}
}

output/
  init.mjs
  _init.mjs
  _top.mjs
  index.mjs
  _unit_open.mjs
  project/
    zapp.prog.mjs
    zapp.prog.mjs.map
  open-abap-core/
    ...
  utilities/
    ...

Names must be valid single directory names on Windows and POSIX. Names are unique without regard to case, and project is reserved. A conflicting derived name needs an explicit libs[].name. Duplicate ABAP objects across libraries are rejected by default; a project object replaces a library object of the same type/name.

Class locals, test classes, function groups, MIME data, and source maps follow their owning object. Source maps include ABAP source content, including libraries loaded from temporary Git checkouts; they use stable library-qualified paths and do not expose the temporary checkout location. Imports and registered MIME filenames reference the new paths.

Shared initialization scripts and test runners remain at the output root. Run programs with node output/project/zapp.prog.mjs; run project unit tests with node output/index.mjs. When migrating from flat output, rebuild a clean generated output directory and update scripts that reference individual modules or assets.

Set incremental_output to true to skip writing unchanged files, replace changed generated files, and remove obsolete files recorded in output/.abap-transpile-manifest.json. The CLI preserves files it did not generate, including custom setup scripts and other user data. Existing output from runs before this option was enabled has no ownership inventory; do one clean build when adopting the option to remove legacy stale files. Set the option to false (the default) to restore unconditional writes. Files generated while it is disabled are not added to the inventory.

The manifest is updated atomically and retained as a recovery aid if a run fails. This does not make the entire output tree transactional. Use one transpiler process per output directory.

The transpiler library retains flat output unless its caller supplies an output folder map as the third argument to Transpiler.run(). This layout is enabled automatically by the CLI.

Pinning a library

A library given by url is cloned when the CLI runs, so without more the default branch of that moment is used and the same project commit can build differently from one day to the next. Set libs[].ref to a commit SHA, a tag or a branch to make the build reproducible:

{
  "libs": [
    {"url": "https://github.com/open-abap/open-abap-core", "ref": "239b817e6fd05e62854fed25663f002c60dda07c"},
    {"url": "https://github.com/example/utilities", "ref": "v1.2.0"}
  ]
}

A branch or tag is cloned shallow. A commit is fetched shallow by name; when the server does not serve that, or the SHA is abbreviated, the full history is fetched and the commit checked out from it. The CLI prints the commit of every library it clones, and of every folder library that is a git checkout, as commit: <sha> next to the file count, so the commits of a build can be recorded.

Duplicate dependencies

By default, two libraries defining the same ABAP object (type and name) cause an Ambiguous dependency object error. To keep existing dependency repositories and skip later copies, set this top-level option in abap_transpile.json:

{
  "skip_duplicate_dependencies": true
}

The first library in libs containing an object wins. Every file of that object in later libraries is skipped, including metadata, class locals, and binary assets. The CLI warns once per skipped object per library, naming the selected library. Imports, output folders, and source maps use the selected copy. Project objects still take precedence over dependencies, and shared package.devc.xml metadata keeps its existing behavior.

Library order now affects generated output. Different definitions can change DDIC types, available methods, and runtime behavior, or cause syntax errors in code expecting the skipped version. This option does not check that copies are equivalent or suppress syntax checking. Put the intended provider first and run your application's tests. For selective control, use libs[].exclude_filter to exclude only the unwanted object's files instead. With incremental_output enabled, changing providers removes obsolete files tracked in the manifest. Use a clean generated output directory when changing providers in legacy mode or when untracked stale output remains from earlier builds.