First meeting (2018-02-20 17:00 UTC)

[killercup]

(will post the notes taken during the meeting here)

[killercup]

For the record: Etherpad right after this meeting

Rust CLI working group

Meta

• Chat: https://gitter.im/rust-lang/WG-CLI
• Coordination repo: https://github.com/rust-lang-nursery/cli-wg
• Next meeting: 2018-02-20 17:00-18:00 UTC on https://gitter.im/rust-lang/WG-CLI
• Nickname: Rust CLIQuE (Rust CLI Quality Enhancement)

Legend: -> = action item

Team members

• eijebong (diesel, servo and randomly bumping dependencies all around the place...)
• epage (Ed Page): cobalt, crate-ci
• DPC (Dylan DPC): co-maintainer of uuid-rs & github-rs
• kbknapp (Kevin Knapp): clap, clog, cargo-{outdated, count, graph}
• killercup (Pascal Hertleif): WG lead, quicli, assert_cli, diesel, cargo-edit
• TeXitoi (Guillaume P.): structopt, benchmarksgame in rust, osmpbfreader, mdo, mimirsbrunn (a geocoder in rust based on elasticsearch), a bit of rust-geo and rs-es
• vitiral (Garrett Berg): artifact, ergo, path_abs, taken
• yoshuawuyts (Yoshua Wuyts)
• sgrif (Sean Griffin): diesel

Slogan ideas

Writing CLI apps in Rust is a frictionless experience with known best practices that work across platforms, good documentation, and effortless distribution

Definition of CLI

A program that is launch in a terminal with parameter, no user interaction during the execution, and that do work on files, network and/or output to terminal

ie not an ncurses TUI
ie not a daemon (@kbknapp: I would argue that I daemon could very well fall into the CLI realm of what's applicable here)

Goals

Areas

• Fun / low friction

• Cross-platform

• Native to each platform

• End-user consumable (distribution)

• Releasing with confidence (testing, etc)

• Rust is known to be a very good language for writing CLI tools

• Writing and distributing a CLI in rust should be more fun than doing so in python.

• "Writing a CLI tool" is a good way to get started with Rust as a beginner

• Make it easy to ship well-tested binaries

• "Writing seamless binaries in Rust should be effortless"

• Rust CLI apps work effectively the same on all platforms

How to get there

• Identify important use-cases and get crates ready
  -> Small survey?
• Blog posts, tutorials, guides, etc. on how to write CLI apps in Rust
• Cookbook? https://rust-lang-nursery.github.io/rust-cookbook/
• quicli docs are written in a cookbook/"let's get shit done" way https://killercup.github.io/quicli/
• "guides as tests" philosophy
• CI book started (will include binary distribution): https://crate-ci.github.io/index.html
• Organizing bin crates (when to mix bin/lib, when to keep separate, managing distinct dependencies)
• Testing / Stability
• Stability this year is a non goal. This year is about experimentation.
• Working on stability for next year or the year after is a goal.
• Do something like "crater" for the CLI ecosystem -- make it easy to have your CLI auto tested with the latest "CLI libraries"
• Create "conglomeration" crates that exposes a "unified" API.
• This is what ergo is attempting: https://github.com/rust-crates/ergo
• Presence on the new Rust site
• Begin describing "ideal workflows"

Crate-wise, I think the thing that could be valuable is to expand on an idea I've seen floated from time to time, creating higher level abstractions over the existing libs. For example, std::path is pretty low level when you compare it to pathlib in Python. If we provide some higher level libs (at the cost of performance or lack of platform neutrality) that'd be a big help for people. They could then progress to the lower level stuff in inner loops

Aspects of writing a CLI tool

• cargo templates?
  -> https://internals.rust-lang.org/t/pre-rfc-cargo-templates/5056
• CLI args handling
• Really solid.
• Next step: Ship clap 3 with structopt-style derive built-in.
  -> help out! Tracking Issue for 3.x clap-rs/clap#1037 and https://github.com/kbknapp/clap-rs/milestone/73
• Colored output
• cf. https://internals.rust-lang.org/t/terminal-platform-abstraction/6746/5
• some crates: termstyle, colored, crossterm, term color, ansi_term
• stabilize ? in main (Tracking issue for RFC 1937: ? in main rust-lang/rust#43301)
  -> help out implementing and testing this issue
• have a good story/guidelines around which exit codes to return
• Streamline logging story
• figure out log vs slog debate
• Error handling. Not all errors are created equal. For example, I/O pipe errors.
• Yes! Providing some official guides on common footguns would go a long way (closed pipes, etc.)
• CI for providing binaries; general guidance on installation options
• cf. https://github.com/japaric/trust/
• https://github.com/crate-ci/crate-ci.github.io by @epage
• cargo-install doesn't respect Cargo.lock
  -> help fix Packages for binary crates should include Cargo.lock rust-lang/cargo#2263
• CLI integration tests
  -> assert_cli 1.0 (@killercup and @epage)
  -> dir-diff 1.0
• Best practices, i.e. testing application code, and not duplicating tests from deps
• Generate documentation
• rustbook only covers Rust API, not CLI API
• documentation of env vars a CLI app repsects/uses
• auto-generate from something like https://docs.rs/configure?
• how to incorporate external crates, like env_logger?
• there seems to be no cohesive answer for man pages yet
• ripgrep is using aciidoc: auto generate man page, update clap, CI cleanup BurntSushi/ripgrep#776
  -> issue in clap Auto-generate manpage, help docs, etc. clap-rs/clap#552 (@kbknapp, awaiting clap v3-alpha)
• flatdoc or mdbook templates/best practices?
  http://ricostacruz.com/flatdoc/

Gotchas

• test harness

  • how to set up clean filesystem/etc environments for testing (containers? chroot jails?
    • tempfile helps
    • dir-diff helps with validation
    • Mocking

• error handling (failure is looking good but does not yet have clear messaging/documentation about how to architect/structure error handling in your app)

• file path handling

  • .., .., // not being auto- handled
  • windows gotchas, like long file paths (which require extended-length paths aka "verbatim paths" as they're called in std)
  • absolute paths on Windows (UNC prefices)
    • https://github.com/notion-cli/notion/blob/master/crates/verbatim/src/lib.rs
  • UTF-8 filenames on MacOS (the filesystem normalizes UTF-8 strings)

• how to package/deploy/distribute

• serialization/deserialization idioms

  • learning how different formats (JSON, TOML, etc) interact with the serde data model
  • best practices and idioms, e.g. "intermediate representation" types that map more closely to the serialization format

• Where to read config files from

  • XDG?)
  • app_dirs crate
    • Is it being maintained?
    • What can be done to help with this?

• Config best practices

  • config crate (handle merging env with file)

• streaming

  • how to thread progress computation through chained readers
  • handling different archive formats (this may be specific to me but I bet others will hit it)
    • how to stream zip files (no crates.io crate supports this AFAIK)
    • how to compute progress percentage of decompressing files

Packaging (Not cargo-install)

• Guides/How-Tos
• Deb, RPM, AUR, Homebrew, Snap, Flatpak, AppImage, nixpkgs
• Automation
• cargo subcommands
• Using CI

If cargo-install is an important use case for dev tools, how much should we look at improving it?

[yoshuawuyts]

@killercup perhaps we could capture the etherpad snapshot in a file too?

[killercup]

@yoshuawuyts the etherpad is versioned already, and most of the content will probably be duplicated in tracking issues, so I wouldn't bother :)

[yoshuawuyts]

@killercup ah yeah, makes sense!

[pickfire]

@killercup What about unifying serde interfaces for different formats as such 3Hren/msgpack-rust#161? As well, can we join the conversation of CLI-WG?

[killercup]

I don't think improving serde adaptors is in scope for the CLI working group.

…

Am 23.02.2018 um 09:39 schrieb Ivan Tham ***@***.***>: @killercup What about unifying serde for different formats as such 3Hren/msgpack-rust#161 ? As well, can we join the conversation of CLI-WG? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.