Consistent xodc CLI

[nkrkv]

Currently, xodc is not usable as it could be. In some points it violates the very basic command line tools standards, poorly validates command arguments, etc. Let’s make xodc great again.

I suggest using yargs as the complete command-line argument parsing solution. What we’re going to achieve:

$ xodc --help
Usage: xodc [command] [options]

Commands:
  resave    opens a project and saves it in another location or format
  install   install libraries or toolchains
  publish   publish a library
  transpile transpile (generate C++) a XOD program
  boards    list supported board names/identifiers
  compile   compile (verify) a XOD program
  upload    upload a XOD program to the board
  help      show help for a specific command

Options:
  -h, --help      show help
  -V, --version   show the version number
  -w, --workspace use the workspace specified, defaults to $HOME/xod
  -q, --quiet     do not log messages other than errors

Run `xodc help COMMAND`  for more information on specific commands.

resave ✔️

$ xodc resave --help
Usage: xodc resave [options] [project]

Options:
  -h, --help      show help
  -V, --version   show the version number
  -w, --workspace use the workspace specified, defaults to $HOME/xod
  -q, --quiet     do not log messages other than errors
  -o, --output    xodball or multifile directory output path, defaults to stdout

Examples:
  xodc resave . -o ~/foo.xodball             Exports the current multifile project to
                                             a xodball
  xodc resave                                Outputs the current multifile project as
                                             a xodball to stdout
  xodc resave foo.xodball -o bar.xodball     Resaves one xodball into another (useful
                                             for applying migrations)
  xodc resave foo.xodball -o /some/new/dir   Converts a xodball to a multifile project

install

$ xodc install --help
Usage: xodc install [options] [lib|arch]

Options:
  -h, --help      show help
  -V, --version   show the version number
  -w, --workspace use the workspace specified, defaults to $HOME/xod
  -q, --quiet     do not log messages other than errors
  --api           XOD API hostname (default: xod.io)

Examples:
  xodc install                              Install all libraries the current
                                            project depends on.
  xodc install bob/utils                    Add/install the `bob/utils`
                                            library
  xodc install bob/utils@0.3.0              Add/install library at the
                                            specific version
  xodc install arduino:sam                  Intall the toolchain for the SAM
                                            architecture of the Arduino package

publish ✔️

$ xodc publish --help
Usage: xodc publish [options] [project]

Options:
  -h, --help      show help
  -V, --version   show the version number
  -w, --workspace use the workspace specified, defaults to $HOME/xod
  -q, --quiet     do not log messages other than errors
  --api           XOD API hostname (default: xod.io)
  --on-behalf     publish on behalf of the username

Examples:
  xodc publish                              Publish the current project with
                                            the version defined in
                                            `project.xod`
  xodc publish foo.xodball                  Publish a project saved as xodball

Prompt for username/password on each invocation, i.e. preserve the current behavior.

---

transpile ✔️

$ xodc transpile --help
Usage: xodc transpile [options] [[project] patch]

Options:
  -h, --help      show help
  -V, --version   show the version number
  -w, --workspace use the workspace specified, defaults to $HOME/xod
  -q, --quiet     do not log messages other than errors
  -o, --output    C++ output file path
  --debug         enable debug traces
  --watches       enable all watches communication

Examples:
  xodc transpile                            Transpile a program using the
                                            cwd patch as entry point,
                                            print to stdout
  xodc transpile main -o x.cpp              Transpile the current project
                                            with `main` patch as entry point,
                                            save the output in `x.cpp`
  xodc transpile foo.xodball main           Transpile a project in the xodball
                                            with `main` patch as entry point

Here and in the commands latter the possible valid value for [[project] patch] can be 0, 1, or 2 arguments.

If zero arguments passed, it is equivalent to passing a single arg .

If a single argument is passed, it can be either of two forms:

1. A file system path to the patch file or directory containing it (like ./main or ./main/patch.xodp)
2. A path to patch in XOD terms (like main or @/main)

In the first case, the project path is automatically deduced from the patch path. In the second case, the project path is automatically deduced from the current working directory.

If two arguments are passed, the first one should be an FS path to a xodball, to a directory inside a multifile project, or to the project.xod file itself. In this case the patch path is only allowed to be specified in XOD terms (case No 2).

The following forms are valid:

• xodc transpile
• xodc transpile .
• xodc transpile main
• xodc transpile @/main
• xodc transpile ./main
• xodc transpile main/
• xodc transpile ./main/patch.xodp
• xodc transpile . main
• xodc transpile foo.xodball main

boards ✔️

$ xodc boards --help
Usage: xodc boards [options]

Options:
  -h, --help      show help
  -V, --version   show the version number
  -q, --quiet     do not log messages other than errors

Example output:

$ xodc boards
Board Name                              FQBN                                      
Adafruit Circuit Playground             arduino:avr:circuitplay32u4cat            
Adafruit Circuit Playground Express     arduino:samd:adafruit_circuitplayground_m0
Arduino BT                              arduino:avr:bt                            
Arduino Due (Native USB Port)           arduino:sam:arduino_due_x                 
Arduino Due (Programming Port)          arduino:sam:arduino_due_x_dbg             
Arduino Duemilanove or Diecimila        arduino:avr:diecimila                     
Arduino Esplora                         arduino:avr:esplora                       
Arduino Ethernet                        arduino:avr:ethernet                      
Arduino Fio                             arduino:avr:fio                           
Arduino Gemma                           arduino:avr:gemma                         
Arduino Industrial 101                  arduino:avr:chiwawa                       
Arduino Leonardo                        arduino:avr:leonardo                      
Arduino Leonardo ETH                    arduino:avr:leonardoeth                   
Arduino M0                              arduino:samd [not installed]
Arduino M0 Pro (Native USB Port)        arduino:samd [not installed]
Arduino M0 Pro (Programming Port)       arduino:samd [not installed]
Arduino MKRFox1200                      arduino:samd [not installed]
Arduino MKRZero                         arduino:samd [not installed]
Arduino Mega ADK                        arduino:avr:megaADK                       
Arduino Mini                            arduino:avr:mini                          
Arduino NG or older                     arduino:avr:atmegang                      
Arduino Nano                            arduino:avr:nano                          
Arduino Pro or Pro Mini                 arduino:avr:pro                           
Arduino Robot Control                   arduino:avr:robotControl                  
Arduino Robot Motor                     arduino:avr:robotMotor                    
Arduino Tian                            arduino:samd [not installed]
Arduino Tian (MIPS Console port)        arduino:samd [not installed]
Arduino Uno WiFi                        arduino:avr:unowifi                       
Arduino Yún                             arduino:avr:yun                           
Arduino Yún Mini                        arduino:avr:yunmini                       
Arduino/Genuino 101                     Intel:arc32:arduino_101                   
Arduino/Genuino MKR1000                 arduino:samd [not installed]
Arduino/Genuino Mega or Mega 2560       arduino:avr:mega                          
Arduino/Genuino Micro                   arduino:avr:micro                         
Arduino/Genuino Uno                     arduino:avr:uno                           
Arduino/Genuino Zero (Native USB Port)  arduino:samd [not installed]
Arduino/Genuino Zero (Programming Port) arduino:samd [not installed]
LilyPad Arduino                         arduino:avr:lilypad                       
LilyPad Arduino USB                     arduino:avr:LilyPadUSB                    
Linino One                              arduino:avr:one                           

compile

$ xodc compile --help
Usage: xodc compile --board <board> [options] [[project] patch]

Options:
  -h, --help      show help
  -V, --version   show the version number
  -w, --workspace use the workspace specified, defaults to $HOME/xod
  -q, --quiet     do not log messages other than errors
  -b, --board     target board identifier                            [required]
  -o, --output    save output binary at the path specified; could be a file
                  path or directory; the same directory is used for intermediate
                  build artifacts
  --debug         enable debug traces
  --watches       enable all watches communication
  --cloud         compile in the cloud
  --anonymous     when compile in the cloud do it anonymously
  --api           XOD API hostname for cloud compilation (default: xod.io)

Examples:
  xodc compile -b arduino:avr:uno           Compile a program using the
                                            current patch as entry point
  xodc compile -b arduino:avr:uno --cloud main
                                            Compile the current project
                                            with `main` patch as entry point,
                                            use cloud compilation
  xodc compile -b arduino:arv:uno foo.xodball main -o bin/uno.hex
                                            Compile the patch `main` from the
                                            xodball project and save binaries
                                            in `bin/uno.hex`

• Prompt for username/password on each invocation if --cloud and not --anonymous
• Fail if a toolchain is not installed
• Exit with the same exit code as a compiler (non-zero on error)
• Stream output in real time

upload

$ xodc upload --help
Usage: xodc upload --board <board> --port <port> [options] [[project] patch]

Options:
  -h, --help      show help
  -V, --version   show the version number
  -w, --workspace use the workspace specified, defaults to $HOME/xod
  -q, --quiet     do not log messages other than errors
  -b, --board     target board identifier                            [required]
  -p, --port      port to use for upload                             [required]
  --debug         enable debug traces
  --watches       enable all watches communication
  --cloud         compile in the cloud
  --anonymous     when compile in the cloud do it anonymously
  --api           XOD API hostname for cloud compilation (default: xod.io)

Examples:
  xodc upload -b arduino:avr:uno -p /dev/ttyACM1
                                            Compile a program using the
                                            current patch as entry point,
                                            upload to ttyACM1.

Requirements are the same as for compile. Stream uploader output in realtime as well.

---

Common points

• Setup xod-cli/package.json properly so that xodc is available after npm install
• Care about error handling and error messages. An error should be a human-friendly: “. ”
• Always exit with non-zero code if an error happened
• Use stderr for log messages and stdout only for the essential job output, test with tee to verify. Obvious: --output does not redirect log messages to the file, the messages stay on stderr even if --output is specified.

[knopki]

What the difference between xodc help COMMAND and xodc COMMAND --help?

[nkrkv]

The same as between:

~
$ git status --help 

~
$ git help status  

No difference

[nkrkv]

The wip label is for PRs. Issues have a column “In progress” in the Project

[nkrkv]

Closed by #1518 and #1548