Add `--split` argument for `xodc transpile`

[evgenykochetkov]

trafficstars

Rationale

Currently, the generated code is output as a single chunk. In some advanced usage scenarios when a custom build system is involved that is undesirable. Particularly, in the case of the FreeRTOS-oriented project where multiple XOD programs run side by side, the code generated by each program should be split, so that the common parts could be re-used. This guarantees code deduplication at the binary level.

User story

Consider a project my-proj-qux with patches main and foo. Let’s assume it also uses some nodes from xod/core and community/customlib. Then, I can run the following:

xodc transpile my-proj-qux.xodball main --split --output ./build/

This will transpile the project and put generated code split by files to the build subdir:

build/
  runtime/
    formatNumber.h
    formatNumber.cpp
    listFuncs.h
    listViews.h
    memory.h
    memory.cpp
    preamble.h
    runtime.cpp
    # and other program-independent source files
    XOD.h
  nodes/
    my_proj_qux__foo.h
    xod__core__add.h
    xod__core__flip_flop.h
    community__customlib__superpatch.h
    # and all other C++ node implemetations referred
  main/
    my_proj_qux__main.cpp

I can transpile another project using the same subdir and its sources will deeply override the existing files and dirs, leaving other existing files as-is. Effectively it will create a minimal project to run multiple programs simultaneously.

All the source files include correct #include directives and header guards, so that I can successfully compile and link together all *.cpp as usual (e.g. with make and avr-gcc).

Acceptance criteria

• [ ] I can xodc transpile --split as described above and have all the source files layed out
• [ ] If --split with --output unspecified, show an error and exit
• [ ] If --split with --output pointing to a file, show an error and exit
• [ ] If --split with --output=foo/bar and bar does not exist, create it
• [ ] If --split with --output=foo/bar and foo does not exist, show an error and exit
• [ ] runtime/XOD.h sums up all the public XOD API in a single file and get’s #include’d in nodes/*.h and main/*.cpp

How to test

• Have a shell script to xodc transpile --split a sample project
• Have a Makefile which shows how to successfully build that project for AVR target

[knopki]

main.cpp — an entry point that ties everything together

Shouldn't the file have a unique name? In the case when several projects are transpiled into one directory with overwriting?

[nkrkv]

Good starting point but many details are missing or overlooked:

(1)

implementations of used patches, each one in a separate file named like user__libname__patchname.cpp

The implementations are potentially C++ template-based, so they can’t be .cpp. They have to be .h. Anyway, you will refer nodes’ evaluate in transactions, so it can’t be just hidden in .cpp.

(2)

The acceptance criteria are missing. How can we judge the feature is implemented or not? The criteria should include a description of specific steps to successfully consume the artifact.

(3)

xodс produces a static runtime.cpp file

No-no. First, you can’t refer anything hidden in .cpp. Second, there are templates that can’t be put in .cpp. Third, and most importantly, the current monolith gluing is done because of that single-file requirement; no reason to union the carefully split source files in this mode.

(4)

Edge cases not described:

• What if ./foo/bar does not exist?
• What if ./foo/bar exists but not empty or not a directory at all?

(5)

As @knopki mentioned, how a user should set the main file name?