I’m pleased to announce a rewrite of Ion in rust to provide a much faster UX and much smaller binary. If you haven’t used Ion, please ignore my previous posts and directly read this one!
Everything in Ion is optimized for terminal UX, including its name - ion is the easiest-to-type name that I find not used by other popular CLI tools, and there it is.
This is still at quite an early stage, but I have been using it for a month myself, so I’d like to share this tool with the community. There will be more detailed documentation and a website set up in the future.
TL;DR let me introduce what commands ion provides currently, you can find more detailed information in the help message by running ion help
Installation
Currently only MacOS and Linux are supported because I don’t know how to release Windows binaries, the MacOS and Linux binaries are packed as a tarball in the release CDN, there is only one binary in it, so just download it and put it wherever you like.
Or you can install by building it from a source if you have a rust compiler setup locally, after cloning the repo, you can just run just install and it will install the binary to .local/bin/ folder.
If you want to have shell auto-completion, after downloading ion, run ion completions <shell> to generate the shell completion script, e.g for oh-my-zsh you can copy and paste the following
cd .oh-my-zsh/completions
ion completions zsh |> _ion
In the future, if this is adopted by more people, maybe we can have juliaup ship this or have an ionup for a friendlier installation process.
The forwarded Pkg commands
Ion forwarded Julia’s Pkg command in the terminal, e.g
> ion add
Add dependencies to current environment
Usage: ion add [OPTIONS] [PACKAGE]...
Arguments:
[PACKAGE]... The package to add
Options:
-g, --global Add the package to the global environment
-h, --help Print help
and all Pkg commands will run as equivalent to having julia --project -e "using Pkg; ... by default, and there is a -g --global option to manage global shared environment.
Releasing a new version with Ion
this has been one of the most frequently used features personally in my previous Julia version, and in this new rust version, I have rewritten the whole thing in a much cleaner and modular fashion.
Have you tired of wanting to bump a patch version, but forgetting it’s already bumped in main and only noticing it’s a wrong patch version after the General registry complains to you after 3min? Have you been tired of opening your editor, changing the version in Project.toml manually then opening a browser to summon JuliaRegistrator but having the bot name typed wrong?
With ion release you only need one line to do all these within seconds! e.g
ion release patch
will automatically bump a patch version based on your current version in main and your registered version, if it’s not a continuous version number ion will warn you and ask if you want to continue, if your current version number is already valid, ion will ask if you want to release that instead, and it will summon JuliaRegistrator directly without asking you to open the browser.
Custom release pipeline with summon and bump
we now also provide bump and summon commands to allow you to do more customization, e.g managing large mono-repo that contains many other packages or maybe you want to pack up some artifact before summon JuliaRegistrator. You can combine these two commands with just (recommended) or make, like what I do here.
Run a standalone script with dependencies
This is a feature that is supported in many other languages Single-file scripts that download their dependencies - DBohdan.com and this has been a gripe from @vchuravy on slack,
You can write the following in your Julia script
# !/usr/bin/env ion run
#=ion
Example = "0.5"
=#
using Pkg
Pkg.status()
println("hello world")
and ion will parse the #=ion ... block to automatically setup an environment, running this will print
> ion run script.jl
Status `~/.local/bin/env/env-3506815430/Project.toml`
[7876af07] Example v0.5.3
hello world
You probably want to ask why this is not a Project.toml or Manifest.toml embedded inside the script like Pluto notebook. Like many other similar implementations, we want this part editable and readable since it will directly appear in your script. Thus if you can install a package with a specific version in Julia REPL by only providing the version number and name, you should be typing the same information in your script too! But we have an alternative mode letting you specify UUID, git revision, URL, path, etc, e.g
# !/usr/bin/env ion run
#=ion
Example = {version="0.5", url="https://github.com/Roger-luo/Example.jl"}
=#
using Pkg
Pkg.status()
println("hello world")
On the other hand, there might be cases where we want a script to be never changed, which is something I’m thinking to have a release mode script environment specification that is similar to Pluto notebook that has a complete Manifest.toml and Project.toml inside the script.
As for normal scripts, in that slack thread @davidanthoff mentioned he wants --project to be the default, which is something I advocate too, and I have been using alias jp="julia --project" in my terminal for years. Though this has been a safety concern for julia compiler binary, it is not a concern for a developer tool that only runs locally. So for a script without the #=ion dependencies, ion run is equivalent to the following (and it forwards Julia compiler flags like --threads etc. if you specify it)
| command | equivalent to |
|---|---|
ion run |
julia --project |
ion run script.jl |
julia --project script.jl |
Clone Julia packages
- Have you gotten annoyed that cloning a Julia package using git ends up in a folder with
xxxx.jlby default? - Have you been opening a browser, searching the package, copying the package git URL, then cloning the package somewhere?
- Have you tried to let
devcommand use your own directory instead of.julia/dev? - Have you cloned a Julia package, ready to contribute to it, but realize you need to fork it and change
remote origintoremote upstreamand add your own fork?
now ion clone handles all above with just one line! if you try
ion clone Example
It will look for the registered URL and try to clone it, and because you don’t seem to have access to this repo, we will ask if you want to fork it and if you say yes, we will do it for you. No opening browser is needed!
Create a new package with pre-defined templates
- have you ever typed the same project configuration again and again interactively with PkgTemplates?
- have you ever typed the wrong option in the interactive mode with PkgTemplates and had to start over entirely?
The ion new command is here to help, we create an entirely new templating system based on PkgTemplates but with serialization in TOML, e.g the following is a project template for small project
name="project"
description = "A project description"
[readme]
[project_file]
[src_dir]
[tests]
and the following is a project template for research packages
name="research"
description = "A research package description"
[project_file]
[readme]
[src_dir]
[documenter]
[license]
[tests]
[repo]
[codecov]
[citation]
[github.ci]
arch = ["x86", "x86_64"]
os = ["ubuntu-latest", "macos-latest", "windows-latest"]
[github.tagbot]
[github.compat_helper]
most importantly you can save your own custom configuration and share it with people! Maybe your company’s internal packages need a custom README template and LICENSE? Create your own template.toml with corresponding components and share it with your colleagues instead of asking them to do it interactively! Check examples in our template registry here!
What’s next?
I’m hoping to have self-update support like juliaup in the future, but I haven’t had the time to work it out, for other features. I’m also thinking about JuliaFormatter and JET integration similar to cargo fmt and cargo clippy, but I haven’t decided on how integration is supported yet.
Last, please feel free to open issues on bug reports, feature requests, or contributing PRs!
