Can't install CLI tool to be used globally in the terminal on Windows

Question

I've made a Rust CLI tool and want to provide download instructions for it to users.

The tool lets you run commands like convert <some args> and lets you convert between numbers with different bases. The key here is I'm trying to enable you running the commands with the keyword convert globally instead of a user having to be in the project directory and run cargo run <args> or ./main <args>.

My Cargo.toml looks like this:

[package]
name = "converter_cli"
version = "0.1.0"
edition = "2021"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]

[[bin]]
name = "convert"
path = "src/main.rs"

Currently, after some research, I've written these instructions which work for my computer (Mac M1):

1. Make sure you have Rust installed on your system. If you don't, use this link.
2. Clone the repo: git clone https://github.com/mattrltrent/base_converter.
3. In the project directory, run cargo build --release.
4. In the project directory, run cargo install --path . (don't miss the ending .).
5. You should now be able to run the tool globally. To be sure, check if you can run convert version.

However, I've ran these instructions on a Windows PC and I get the error "Invalid drive specification", when trying to run convert <args>.

Is there a better way to make this distributable (without publishing it as a Cargo crate) for Linux, Windows, and MacOS in one unified way? Or if not, why don't these instructions work for Windows?

If relevant, my file structure is as follows:

assets
-> <random image assets>
src
-> conversions.rs
-> errors.rs
-> main.rs
target
.gitignore
Cargo.lock
Cargo.toml
README.md

Answer 1

The naming issue

The name is overshadowed by system-builtin:

convert is already a valid command:

Converts a disk from one disk type to another.

• https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/convert

Here are some solutions:

1. Reference your application via full path (ugly, but should do the trick)
2. Specifically alias your application on Windows
3. Rename your application to a somewhat more unique name

Distributing

Distributing is quite a big topic.

Think about how you usually install new software. Behaviour differs from not only people but the used OS, restrictions of the user (admin rights), ...

Provide a compiled program

(as @PaulDempsey already suggested) (in general most people are used to that)

where

• as release in GitHub
• on a dedicated webpage
• on some software portal / app store

how

• simply the binary (aka *.exe)
• wrapped in an installer

Add your package to package manager repositories

there are a bunch of package managers to consider and there are different approaches to get ones own application in there but there are e.g.:

• brew for macOS
• apt, pacman and many more for Linux
• choco for Windows
• ...

Some of them might compile stuff for you others you might simply ship executables with.

Convert your steps into an install script

Most of your steps can easily be converted to a shell and/or batch script so the user can simply run install.sh and everything is good to go. This way you can automatically differentiate behaviors on different systems.