Cross-Platform CLI Considerations

21 min read

A CLI you ship is run on machines you will never see: a colleague’s Windows laptop, a Linux CI runner, your own Mac. The bytes a program reads and writes, the way it spells a file path, and the number it returns when it exits all differ subtly between operating systems. Rust gives you compile-time tools (#[cfg(...)], cfg!(...)) and portable standard-library types (Path, ExitCode) that let you write one program that behaves correctly everywhere.

Quick Overview

Cross-platform correctness is mostly about four things: line endings (\n vs \r\n), paths (separator, drive letters, case-sensitivity), OS detection (cfg!(windows) / #[cfg(...)]), and exit codes (the integer your process returns to the shell). Rust’s standard library models these portably — Path/PathBuf abstract over separators, ExitCode types your process result, and cfg! lets a single binary branch on the target OS. For a TypeScript/JavaScript developer, this is the same role played by os.EOL, path.sep, process.platform, and process.exitCode in Node — but Rust pushes most of it into the type system and the compiler, so a wrong assumption tends to fail to compile rather than corrupt a file in production.

Note: This page covers the cross-platform mindset: line endings, OS detection, and exit codes. The mechanics of building and manipulating paths live in path-handling.md, reading and writing files in file-io.md, environment variables in environment-vars.md, and shipping binaries for each platform in distribution.md. Here we focus on the gotchas that bite when the same code runs on a different OS.

TypeScript/JavaScript Example

A Node CLI that normalizes a file’s line endings, then reports a meaningful exit status. This is the kind of tool you might run in a pre-commit hook.

1
// crlf.ts — run with: npx tsx crlf.ts --lf file.txt
2
import { readFileSync, writeFileSync } from "node:fs";
3
import { EOL } from "node:os";
4
import { sep } from "node:path";
5
import { basename } from "node:path";
6

7
const [mode, ...files] = process.argv.slice(2);
8

9
// Node tells you about the host platform at runtime:
10
console.error(`platform=${process.platform} eol=${JSON.stringify(EOL)} sep=${JSON.stringify(sep)}`);
11

12
if (mode !== "--lf" && mode !== "--crlf") {
13
  console.error("usage: crlf <--lf|--crlf> <file>...");
14
  process.exit(2); // 2 = usage error, by convention
15
}
16

17
const target = mode === "--lf" ? "\n" : "\r\n";
18
let failed = false;
19

20
for (const file of files) {
21
  try {
22
    const text = readFileSync(file, "utf8");
23
    // Collapse every CRLF to LF first, then expand to the target.
24
    const normalized = text.replace(/\r\n/g, "\n").replace(/\n/g, target);
25
    if (normalized !== text) {
26
      writeFileSync(file, normalized);
27
      console.log(`converted ${basename(file)}`);
28
    } else {
29
      console.log(`unchanged ${basename(file)}`);
30
    }
31
  } catch (err) {
32
    console.error(`crlf: ${file}: ${(err as Error).message}`);
33
    failed = true;
34
  }
35
}
36

37
// Setting process.exitCode lets the event loop drain before exiting.
38
process.exitCode = failed ? 1 : 0;

Key points and weak spots:

process.platform is a runtime string ("win32", "darwin", "linux"). There is no compile step, so a platform-specific bug only shows up when that platform runs the code.
os.EOL is "\r\n" on Windows and "\n" everywhere else — but readFileSync(..., "utf8") does not normalize endings for you; you do it by hand with a regex.
process.exit(n) terminates immediately and can truncate buffered stdout; process.exitCode = n is the safer idiom. Exit codes are plain JavaScript numbers with no type checking — passing 256 silently wraps to 0.
path.sep and path.basename keep you off the literal /, but nothing stops you from writing file.split("/") and shipping a Windows bug.

Rust Equivalent

The same tool in idiomatic Rust. Notice that line endings are handled with the standard library, paths never touch a literal separator, and the exit status is a typed ExitCode rather than a bare integer.

1
use std::fs;
2
use std::path::PathBuf;
3
use std::process::ExitCode;
4

5
/// The newline style a file should use.
6
#[derive(Clone, Copy)]
7
enum Ending {
8
    Lf,
9
    Crlf,
10
}
11

12
/// How `run` failed, so `main` can pick a conventional exit code.
13
enum RunError {
14
    /// A bad invocation the caller can fix: unknown/missing mode, no files.
15
    Usage(String),
16
    /// A file could not be read or written.
17
    Io(String),
18
}
19

20
/// Normalize every line ending in `text` to `target`.
21
fn normalize(text: &str, target: Ending) -> String {
22
    // Collapse CRLF -> LF first so mixed-ending files become uniform,
23
    // then expand to the requested style. This is deterministic.
24
    let lf = text.replace("\r\n", "\n");
25
    match target {
26
        Ending::Lf => lf,
27
        Ending::Crlf => lf.replace('\n', "\r\n"),
28
    }
29
}
30

31
fn run() -> Result<(), RunError> {
32
    let mut args = std::env::args().skip(1);
33
    let mode = args
34
        .next()
35
        .ok_or_else(|| RunError::Usage("usage: crlf <--lf|--crlf> <file>...".to_string()))?;
36
    let target = match mode.as_str() {
37
        "--lf" => Ending::Lf,
38
        "--crlf" => Ending::Crlf,
39
        other => return Err(RunError::Usage(format!("unknown mode: {other}"))),
40
    };
41

42
    let files: Vec<PathBuf> = args.map(PathBuf::from).collect();
43
    if files.is_empty() {
44
        return Err(RunError::Usage("no input files".to_string()));
45
    }
46

47
    for path in &files {
48
        let text = fs::read_to_string(path)
49
            .map_err(|e| RunError::Io(format!("{}: {e}", path.display())))?;
50
        let out = normalize(&text, target);
51
        if out != text {
52
            fs::write(path, &out).map_err(|e| RunError::Io(format!("{}: {e}", path.display())))?;
53
            println!("converted {}", path.display());
54
        } else {
55
            println!("unchanged {}", path.display());
56
        }
57
    }
58
    Ok(())
59
}
60

61
fn main() -> ExitCode {
62
    if cfg!(windows) {
63
        eprintln!("platform=windows");
64
    } else {
65
        eprintln!("platform=unix");
66
    }
67

68
    match run() {
69
        Ok(()) => ExitCode::SUCCESS,
70
        Err(RunError::Usage(msg)) => {
71
            eprintln!("crlf: {msg}");
72
            ExitCode::from(2) // 2 = usage error, mirroring the Node version
73
        }
74
        Err(RunError::Io(msg)) => {
75
            eprintln!("crlf: {msg}");
76
            ExitCode::from(1) // 1 = I/O failure
77
        }
78
    }
79
}

Running it against a CRLF file on macOS/Linux produces this real output (the file is rewritten with LF-only line endings, verified with a hex dump):

1
platform=unix
2
converted /tmp/test.txt

A second run is a no-op, and a missing file exits with status 1:

1
platform=unix
2
unchanged /tmp/test.txt

1
platform=unix
2
crlf: /tmp/does-not-exist.txt: No such file or directory (os error 2)

The shell sees exit code 2 for a usage error (an unknown mode, a missing mode, or no input files), 1 for an I/O failure, and 0 for success — the same contract the Node version encodes with process.exit(2) and process.exitCode = 1, and exactly what a Makefile, CI step, or pre-commit hook depends on. The RunError enum is what keeps the two failure classes distinct so main can map each to the right code.

Detailed Explanation

Line endings

A text file’s line ending is just bytes. Unix-family systems (Linux, macOS) use a single line feed \n (0x0A). Windows uses a carriage-return + line-feed pair \r\n (0x0D 0x0A), inherited from typewriters and DOS. The classic cross-platform bug is reading a Windows file on Linux and getting a stray \r on the end of every “line”.

Rust’s standard library leans your way here. str::lines() splits on \n and strips a trailing \r if present, so it transparently handles both styles:

1
fn main() {
2
    let windows_text = "line one\r\nline two\r\nline three\r\n";
3
    for (i, line) in windows_text.lines().enumerate() {
4
        // `{line:?}` prints with quotes, so a stray `\r` would be visible.
5
        println!("{i}: {line:?}");
6
    }
7
}

Real output — note that there is no trailing \r in any line:

1
0: "line one"
2
1: "line two"
3
2: "line three"

This is the same convenience as JavaScript’s text.split(/\r?\n/), but built into the iterator you would reach for anyway. The catch: lines() only helps on read. When you write, Rust emits exactly the bytes you give it — writeln! and println! always emit \n, never \r\n, on every platform. That is usually what you want (LF is the portable default and Git normalizes for you), but if you must produce CRLF for a Windows-only consumer, do it explicitly:

1
fn main() {
2
    // Collapse to LF, then expand — handles mixed-ending input.
3
    let normalized = "a\r\nb\nc".replace("\r\n", "\n");
4
    println!("LF form  = {normalized:?}");
5
    let crlf = normalized.replace('\n', "\r\n");
6
    println!("CRLF form = {crlf:?}");
7
}

Real output:

1
LF form  = "a\nb\nc"
2
CRLF form = "a\r\nb\r\nc"

Tip: Reading with fs::read_to_string then writing with fs::write preserves the bytes you produce; it does not silently convert endings. This is the opposite of some text editors and unlike Python’s text-mode open(). If you want LF everywhere, normalize on write.

Detecting the OS: `cfg!` vs `#[cfg(...)]`

Rust gives you two related tools, and the difference matters.

cfg!(...) is a macro that evaluates to a bool at compile time but is used like a normal runtime expression. Both branches of the surrounding if must type-check and compile, even on the platform where the condition is false:

1
fn main() {
2
    let shell = if cfg!(windows) { "cmd.exe" } else { "/bin/sh" };
3
    println!("default shell: {shell}");
4
}

Real output on macOS:

1
default shell: /bin/sh

#[cfg(...)] is an attribute that includes or excludes the item entirely before type-checking. Code behind a #[cfg(windows)] that doesn’t compile on macOS is simply not compiled there — which lets you call Windows-only APIs without #[cfg]-ing every use:

1
#[cfg(windows)]
2
fn config_template() -> &'static str {
3
    "%APPDATA%\\mytool" // only compiled on Windows
4
}
5

6
#[cfg(not(windows))]
7
fn config_template() -> &'static str {
8
    "$HOME/.config/mytool"
9
}
10

11
fn main() {
12
    println!("config: {}", config_template());
13
}

Real output on macOS:

1
config: $HOME/.config/mytool

You can also query the target at runtime via std::env::consts:

1
fn main() {
2
    println!("OS         = {}", std::env::consts::OS);          // "macos", "windows", "linux"
3
    println!("FAMILY     = {}", std::env::consts::FAMILY);      // "unix" or "windows"
4
    println!("EXE_SUFFIX = {:?}", std::env::consts::EXE_SUFFIX);// ".exe" on Windows, "" elsewhere
5
}

Real output on macOS:

1
OS         = macos
2
FAMILY     = unix
3
EXE_SUFFIX = ""

These are baked in at compile time for the target you built for, so cross-compiling from a Mac to Windows reports windows/.exe, not your host. The common cfg keys are target_os ("windows", "macos", "linux", "android", …), target_family ("unix", "windows", "wasm"), target_arch ("x86_64", "aarch64", …), and the shorthands unix / windows.

Note: Prefer #[cfg(...)] when an entire function or use only makes sense on one OS, and cfg!(...) for a small inline branch where both arms compile everywhere. #[cfg(...)] keeps platform-specific imports out of the other platform’s build entirely.

Paths

Paths are the densest source of portability bugs, so they get their own page (path-handling.md). The cross-platform rule of thumb: never hardcode a separator, never split a path on '/'. Build paths with Path::join or collect components, and the right separator is inserted for the target:

1
use std::path::{Path, PathBuf};
2

3
fn main() {
4
    let p: PathBuf = ["config", "app", "settings.toml"].iter().collect();
5
    println!("joined = {}", p.display());
6
    println!("separator = {:?}", std::path::MAIN_SEPARATOR);
7

8
    let f = Path::new("archive.tar.gz");
9
    println!("extension = {:?}", f.extension()); // last component only
10
    println!("file_name = {:?}", f.file_name());
11
}

Real output on macOS (on Windows the same code joins with \ and reports '\\'):

1
joined = config/app/settings.toml
2
separator = '/'
3
extension = Some("gz")
4
file_name = Some("archive.tar.gz")

Exit codes

The exit code is the single integer your process hands back to the shell. By convention 0 means success and non-zero means failure; tools layer meaning on top (grep returns 1 for “no match”, 2 for a real error). On Unix only the low 8 bits are kept (so 256 becomes 0), which is exactly why typing the code matters.

Rust offers three ways to set it:

Return ExitCode from main (preferred). main() -> ExitCode runs all destructors first, then exits with ExitCode::SUCCESS (0), ExitCode::FAILURE (1), or ExitCode::from(n) for any u8.
Return Result<(), E> from main. Ok exits 0; Err prints the error’s Debug representation to stderr and exits with ExitCode::FAILURE (1).
Call std::process::exit(n). This terminates immediately and skips destructors — the analogue of process.exit(). Use it only when you genuinely need to bail out early.

The typed u8 of ExitCode::from is the safety win over JavaScript’s number: you cannot accidentally pass 300 and have it wrap to a misleading 44. To map error kinds to conventional codes (here, BSD sysexits.h style):

1
use std::io;
2
use std::process::ExitCode;
3

4
fn exit_code_for(err: &io::Error) -> ExitCode {
5
    match err.kind() {
6
        io::ErrorKind::NotFound => ExitCode::from(66),         // EX_NOINPUT
7
        io::ErrorKind::PermissionDenied => ExitCode::from(77), // EX_NOPERM
8
        _ => ExitCode::from(74),                               // EX_IOERR
9
    }
10
}
11

12
fn main() -> ExitCode {
13
    let path = "/tmp/definitely-not-here-xyz";
14
    match std::fs::read_to_string(path) {
15
        Ok(_) => ExitCode::SUCCESS,
16
        Err(e) => {
17
            eprintln!("error reading {path}: {e}");
18
            exit_code_for(&e)
19
        }
20
    }
21
}

Real output (and the shell sees exit code 66):

1
error reading /tmp/definitely-not-here-xyz: No such file or directory (os error 2)

Warning: The OS error text is platform-specific. On Unix a missing file reports No such file or directory (os error 2); on Windows the same operation reports The system cannot find the file specified. (os error 2). Match on err.kind(), never on the message string.

Key Differences

Concern	TypeScript / Node	Rust
OS detection	`process.platform` (runtime string)	`cfg!(windows)` / `#[cfg(...)]` (compile-time) + `std::env::consts::OS`
Native EOL	`os.EOL` (`"\r\n"` on Windows, else `"\n"`)	No single constant; `println!`/`writeln!` always emit `\n`; `lines()` strips `\r` on read
Path separator	`path.sep`, `path.delimiter`	`std::path::MAIN_SEPARATOR`; `Path::join` inserts it for you
Path type	strings, normalized by `path` module	`Path` / `PathBuf` (own type; not a `String`)
Exit code type	`number` (silently wraps mod 256)	`ExitCode` wrapping a typed `u8`
Immediate exit	`process.exit(n)` (skips cleanup)	`std::process::exit(n)` (skips destructors)
Graceful exit	`process.exitCode = n`	`main() -> ExitCode` (runs destructors)
Where bugs surface	at runtime, on the affected OS	many at compile time; the rest via portable types

The deeper conceptual difference: Node defers everything to runtime, Rust pushes it to compile time. A #[cfg(windows)] block that references a non-existent Unix API never compiles on Linux, so an entire class of “works on my machine” bugs cannot ship. The trade-off is that you must think about the target at build time — and that cross-compiling means the cfgs reflect the target, not your dev box.

Unlike TypeScript, there is no os.EOL-style “native newline” constant that Rust’s output macros consult. Rust’s stance is that LF is the portable default and your output should be deterministic regardless of host; convert to CRLF only when a specific consumer demands it.

Common Pitfalls

Pitfall 1: Splitting a path on a literal `'/'`

1
fn main() {
2
    let raw = "config/app/settings.toml";
3
    // Works on Unix, WRONG on Windows where '\' separates components.
4
    let last = raw.rsplit('/').next().unwrap();
5
    println!("buggy last = {last}");
6
}

This compiles and looks fine on your Mac, then misbehaves on a Windows path like config\app\settings.toml. The fix is to let Path parse it:

1
use std::path::Path;
2

3
fn main() {
4
    let raw = "config/app/settings.toml";
5
    let last = Path::new(raw).file_name().unwrap();
6
    println!("correct = {last:?}");
7
}

Real output: correct = "settings.toml". See path-handling.md for the full story.

Pitfall 2: Printing a `Path` with `{}`

Path and OsStr deliberately do not implement Display, because they may contain bytes that are not valid UTF-8 (legal on Unix, and on Windows paths are UTF-16). Writing println!("{}", some_path) fails to compile:

1
use std::path::Path;
2

3
fn main() {
4
    let p = Path::new("/etc/hosts");
5
    println!("path is {}", p); // does not compile (error[E0277])
6
}

The real compiler error is explicit about the fix:

1
error[E0277]: `Path` doesn't implement `std::fmt::Display`
2
 --> src/main.rs:5:28
3
  |
4
5 |     println!("path is {}", p); // does not compile (error[E0277])
5
  |                       --   ^ `Path` cannot be formatted with the default formatter; call `.display()` on it
6
  |                       |
7
  |                       required by this formatting parameter
8
  |
9
  = help: the trait `std::fmt::Display` is not implemented for `Path`
10
  = note: in format strings you may be able to use `{:?}` (or {:#?} for pretty-print) instead
11
  = note: call `.display()` or `.to_string_lossy()` to safely print paths, as they may contain non-Unicode data
12
  = note: required for `&Path` to implement `std::fmt::Display`

Use p.display() for human output, or p.to_string_lossy() when you need an owned String (it replaces invalid bytes with �).

Pitfall 3: Comparing extensions case-sensitively

On Windows and the default macOS filesystem, PHOTO.JPG and photo.jpg are the same file, and extensions are not case-significant. A naive equality check silently misbehaves:

1
use std::path::Path;
2

3
fn main() {
4
    let p = Path::new("PHOTO.JPG");
5
    // case-sensitive — false even though this IS a jpg
6
    let naive = p.extension().map(|e| e == "jpg").unwrap_or(false);
7
    // case-insensitive — correct
8
    let correct = p
9
        .extension()
10
        .and_then(|e| e.to_str())
11
        .map(|e| e.eq_ignore_ascii_case("jpg"))
12
        .unwrap_or(false);
13
    println!("naive = {naive}, correct = {correct}");
14
}

Real output: naive = false, correct = true.

Pitfall 4: Reaching for `std::process::exit` and losing your cleanup

std::process::exit(1) terminates the process right now — buffered writers are not flushed and Drop impls do not run. If you wrote to a BufWriter (see file-io.md) and then called process::exit, you can lose the unflushed tail. Prefer returning an ExitCode (or a Result) from main so the stack unwinds normally. The Node mirror is preferring process.exitCode = n over process.exit(n).

Pitfall 5: Matching on OS error messages

err.to_string() differs across platforms (see the Warning above). Code that does if msg.contains("No such file") works on Linux and silently fails on Windows. Match on err.kind() instead — io::ErrorKind is the portable, stable surface.

Best Practices

Default to LF on write. Emit \n everywhere and let Git’s core.autocrlf / .gitattributes handle checkout conversion. Produce CRLF only for a consumer that explicitly requires it.
Read with lines() / read_to_string and rely on \r stripping rather than hand-rolling a regex. For binary-safe line splitting, read bytes and split on b'\n'.
Never hardcode separators. Build paths with Path::join or [..].iter().collect::<PathBuf>(); query std::path::MAIN_SEPARATOR only for display.
Print paths with .display(), and store them as PathBuf, not String.
Type your exit codes. Return ExitCode from main; reserve std::process::exit for genuine early aborts and flush buffers first.
Adopt an exit-code convention and document it in --help: 0 success, 1 expected failure, 2 usage error is a widely understood baseline (it matches grep and many GNU tools).
Reach for cfg! for inline branches and #[cfg] for whole items. Keep platform-only imports behind #[cfg] so the other platform never compiles them.

Use the dirs crate for standard locations instead of building ~/.config paths by hand — it returns the correct per-platform directory at runtime (XDG on Linux, Library/Application Support on macOS, %APPDATA% on Windows). Add it with cargo add dirs:

1
fn main() {
2
    println!("config = {:?}", dirs::config_dir());
3
    println!("cache  = {:?}", dirs::cache_dir());
4
    println!("home   = {:?}", dirs::home_dir());
5
}

Real output on macOS (paths differ per platform and user):

1
config = Some("/Users/ahmet/Library/Application Support")
2
cache  = Some("/Users/ahmet/Library/Caches")
3
home   = Some("/Users/ahmet")

Test on all targets in CI. A matrix build across ubuntu-latest, macos-latest, and windows-latest catches separator and EOL bugs before users do. Distribution and release builds are covered in distribution.md.

Real-World Example

A small tree-clean utility that walks a directory, normalizes every .txt file’s line endings to LF, refuses to touch files outside the given root, and returns conventional exit codes. It demonstrates portable path handling, line-ending normalization, OS detection for a friendly banner, and typed exit codes working together.

1
use std::fs;
2
use std::path::{Path, PathBuf};
3
use std::process::ExitCode;
4

5
/// Recursively collect `.txt` files under `root`.
6
fn collect_txt(root: &Path, out: &mut Vec<PathBuf>) -> std::io::Result<()> {
7
    for entry in fs::read_dir(root)? {
8
        let entry = entry?;
9
        let path = entry.path();
10
        if path.is_dir() {
11
            collect_txt(&path, out)?;
12
        } else if path
13
            .extension()
14
            .and_then(|e| e.to_str())
15
            .map(|e| e.eq_ignore_ascii_case("txt"))
16
            .unwrap_or(false)
17
        {
18
            out.push(path);
19
        }
20
    }
21
    Ok(())
22
}
23

24
/// Normalize `text` to LF-only endings.
25
fn to_lf(text: &str) -> String {
26
    text.replace("\r\n", "\n")
27
}
28

29
fn run(root: &Path) -> Result<usize, String> {
30
    if !root.is_dir() {
31
        return Err(format!("{} is not a directory", root.display()));
32
    }
33

34
    let mut files = Vec::new();
35
    collect_txt(root, &mut files).map_err(|e| format!("{}: {e}", root.display()))?;
36

37
    let mut changed = 0;
38
    for path in &files {
39
        let text = fs::read_to_string(path).map_err(|e| format!("{}: {e}", path.display()))?;
40
        let lf = to_lf(&text);
41
        if lf != text {
42
            fs::write(path, &lf).map_err(|e| format!("{}: {e}", path.display()))?;
43
            println!("normalized {}", path.display());
44
            changed += 1;
45
        }
46
    }
47
    Ok(changed)
48
}
49

50
fn main() -> ExitCode {
51
    // A tiny platform banner — both arms compile on every OS.
52
    let host = if cfg!(windows) { "Windows" } else { "Unix-like" };
53
    eprintln!("tree-clean on {host} ({})", std::env::consts::OS);
54

55
    let root = match std::env::args().nth(1) {
56
        Some(p) => PathBuf::from(p),
57
        None => {
58
            eprintln!("usage: tree-clean <directory>");
59
            return ExitCode::from(2); // usage error
60
        }
61
    };
62

63
    match run(&root) {
64
        Ok(0) => {
65
            println!("nothing to do");
66
            ExitCode::SUCCESS
67
        }
68
        Ok(n) => {
69
            println!("normalized {n} file(s)");
70
            ExitCode::SUCCESS
71
        }
72
        Err(msg) => {
73
            eprintln!("tree-clean: {msg}");
74
            ExitCode::FAILURE // exit code 1
75
        }
76
    }
77
}

Built and run against a directory containing a CRLF file notes.txt and an already-LF readme.txt, this prints (real output, captured on macOS):

1
tree-clean on Unix-like (macos)
2
normalized /tmp/demo/notes.txt
3
normalized 1 file(s)

Running with no argument exits 2; pointing it at a non-directory exits 1. On Windows the banner reads tree-clean on Windows (windows) and the same logic applies — the path joining, extension comparison, and exit codes are all portable. This pairs naturally with clap for richer argument parsing (clap-derive.md) and indicatif for a progress bar on large trees (progress-bars.md).

Exercises

Exercise 1: Report the host platform

Difficulty: Beginner

Objective: Use cfg! and std::env::consts to print a platform summary.

Instructions: Write a program that prints a single line of the form os=<os> family=<family> sep=<separator>, using std::env::consts::OS, std::env::consts::FAMILY, and std::path::MAIN_SEPARATOR. Then add an if cfg!(windows) branch that prints mode=windows or mode=unix on a second line.

Solution

1
fn main() {
2
    println!(
3
        "os={} family={} sep={:?}",
4
        std::env::consts::OS,
5
        std::env::consts::FAMILY,
6
        std::path::MAIN_SEPARATOR,
7
    );
8
    if cfg!(windows) {
9
        println!("mode=windows");
10
    } else {
11
        println!("mode=unix");
12
    }
13
}

Real output on macOS:

1
os=macos family=unix sep='/'
2
mode=unix

Exercise 2: A line-ending detector with exit codes

Difficulty: Intermediate

Objective: Read a file and exit with a code that reflects its line-ending style.

Instructions: Take a file path as the first argument. Read it with fs::read_to_string. Exit 0 if the file contains only LF endings (no \r\n), 1 if it contains any CRLF, and 2 for a usage/IO error (no argument, or the file can’t be read). Print a human-readable summary to stderr. Return an ExitCode from main.

Solution

1
use std::fs;
2
use std::process::ExitCode;
3

4
fn main() -> ExitCode {
5
    let path = match std::env::args().nth(1) {
6
        Some(p) => p,
7
        None => {
8
            eprintln!("usage: detect <file>");
9
            return ExitCode::from(2);
10
        }
11
    };
12

13
    let text = match fs::read_to_string(&path) {
14
        Ok(t) => t,
15
        Err(e) => {
16
            eprintln!("detect: {path}: {e}");
17
            return ExitCode::from(2);
18
        }
19
    };
20

21
    if text.contains("\r\n") {
22
        eprintln!("{path}: contains CRLF endings");
23
        ExitCode::from(1)
24
    } else {
25
        eprintln!("{path}: LF only");
26
        ExitCode::SUCCESS
27
    }
28
}

Given a file unix.txt written with LF only, this prints unix.txt: LF only to stderr and exits 0; given a CRLF file it prints ... contains CRLF endings and exits 1. (Verified: a printf 'a\r\nb\r\n' file yields exit 1, a printf 'a\nb\n' file yields exit 0.)

Exercise 3: Platform-specific config path with conditional compilation

Difficulty: Advanced

Objective: Use #[cfg(...)] to compile a different config_path per OS, and verify the choice with the dirs crate.

Instructions: Write a config_path() function that returns a PathBuf to mytool/config.toml inside the platform’s config directory. Implement it two ways and compare: (a) a hand-rolled version using #[cfg(windows)] / #[cfg(not(windows))] that joins onto dirs::config_dir(), falling back to the current directory if None; and (b) confirm both branches type-check by printing the result. Add dirs with cargo add dirs. Bonus: explain in a comment why #[cfg] is preferable to cfg! here.

Solution

1
use std::path::PathBuf;
2

3
// `#[cfg]` is preferable to `cfg!` here because the two branches build
4
// genuinely different file names; with `#[cfg]` only the matching item is
5
// compiled, so neither version pays for the other's string at runtime.
6

7
#[cfg(windows)]
8
fn app_subdir() -> &'static str {
9
    "MyTool" // Windows convention: PascalCase app folder
10
}
11

12
#[cfg(not(windows))]
13
fn app_subdir() -> &'static str {
14
    "mytool" // Unix convention: lowercase
15
}
16

17
fn config_path() -> PathBuf {
18
    let base = dirs::config_dir().unwrap_or_else(|| PathBuf::from("."));
19
    base.join(app_subdir()).join("config.toml")
20
}
21

22
fn main() {
23
    println!("config path: {}", config_path().display());
24
}

Real output on macOS (the config dir and app folder differ per platform):

1
config path: /Users/ahmet/Library/Application Support/mytool/config.toml

On Windows the same binary would resolve to something like C:\Users\<you>\AppData\Roaming\MyTool\config.toml, and on Linux to /home/<you>/.config/mytool/config.toml — all from one source file, because dirs resolves the base at runtime and #[cfg] selects the app-folder name at build time.

Cross-Platform CLI Considerations

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

Line endings

Detecting the OS: cfg! vs #[cfg(...)]

Paths

Exit codes

Key Differences

Common Pitfalls

Pitfall 1: Splitting a path on a literal '/'

Pitfall 2: Printing a Path with {}

Pitfall 3: Comparing extensions case-sensitively

Pitfall 4: Reaching for std::process::exit and losing your cleanup

Pitfall 5: Matching on OS error messages

Best Practices

Real-World Example

Further Reading

Exercises

Exercise 1: Report the host platform

Exercise 2: A line-ending detector with exit codes

Exercise 3: Platform-specific config path with conditional compilation

Detecting the OS: `cfg!` vs `#[cfg(...)]`

Pitfall 1: Splitting a path on a literal `'/'`

Pitfall 2: Printing a `Path` with `{}`

Pitfall 4: Reaching for `std::process::exit` and losing your cleanup