diff --git a/README.md b/README.md index df93683..5eb2d63 100644 --- a/README.md +++ b/README.md @@ -6,8 +6,6 @@ Ion is a CLI toolbox for Julia developer. It provides a set of tools to help you develop Julia packages. -Announcement: https://discourse.julialang.org/t/ann-the-ion-command-line-for-julia-developers-written-in-rust/94495 - ## Installation ### pre-build binary @@ -22,287 +20,10 @@ Using [`just`](https://github.com/casey/just) and [Rust's cargo/rustc compiler]( just install ``` +## Documentation -### Overview -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. - -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 - Details - -Currently only MacOS and Linux are supported; the MacOS and Linux binaries are packed as a tarball in the release CDN. There is only one binary in the release, so just download it and put it wherever you like. Also, if anyone would like to contribute their knowledge about how to release Windows binaries, that would be appreciated! - -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 the .local/bin/ folder. - -If you want to have shell auto-completion, after downloading ion, run ion completions 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 forwards Julia's Pkg commands 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 Ion will also summon JuliaRegistrator directly without asking you to open the browser. - -#### Releases - -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`](https://github.com/casey/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. The lack of this feature has been a gripe from users in the Julia community; Ion solves this pain point with its new script system. - -You can write the following in your Julia script -```Julia -# !/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! - -We also have an alternative mode letting you specify UUID, git revision, URL, path, etc, e.g - -```julia -# !/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. - -#### A Local Environment by Default - -As for normal scripts, many Julia users want `julia --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.jl by 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 dev command 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 origin to remote upstream and 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. - -The following is a project template for a small project: - -```TOML -name="project" -description = "A project description" - -[readme] -[project_file] -[src_dir] -[tests] -``` - -and the following is a project template for research packages: - -```TOML -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](https://github.com/Roger-luo/ion-templates)! - -#### 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! - -### Command Quick Reference: - -| Commands | Description | -| ---------------------------- | ------------------------------------------------------------ | -| new [PATH] | Create a new package | -| clone [URL] [PATH] | Clone a package from URL or registry | -| release [VERSION] [PATH] | release a new version of a package | -| bump [VERSION] [PATH] | bump the version of a package | -| summon [PATH] | summon JuliaRegistrator to register the package | -| run [PATH] | Run a script, or start a REPL if no script is given | -| script update/rm/repl [PATH] | script tools | -| add [PACKAGE...] | Add dependencies to current environment | -| remove [PACKAGE...] | Remove dependencies in the current environment [aliases: rm] | -| develop [PACKAGE] | Develop packages in the current environment [aliases: dev] | -| free [PACKAGE] | Free pinned packages in the current environment | -| gc | garbage collect packages not used for a significant time | -| precompile [PACKAGE...] | Precompile all packages in the current environment | -| status | Show the status of the current environment [aliases: st] | -| update [PACKAGE...] | Update the current environment [aliases: up] | -| why [PACKAGE] | show why a package is installed | -| template list/update/inspect | template management | -| completions [SHELL] | generate shell completion scripts | -| auth login/logout | manage Github authentication | - ---- -#### Command List - -NB: sub-commands are indicated with bullet points and options are indicated with bullet points plus short or long flags (ie. -f or --flag). -Arguments are listed in square brackets, such as [URL]. A positional arg which is capable of handling multiple arguments is listed with ellipses following the name (eg. [EXAMPLE...]). - -Optional arguments are listed with a `?` before the name; generally speaking, if required arguments are not provided, Ion will ask for them. - - ion -- auth - - login - - logout -- clone [?options] [URL] [PATH] - - --registry [REGISTRY] -- release [?options] [VERSION] [PATH] - - --branch | -b [?BRANCH] - - --registry [?REGISTRY] - - --no-prompt - - --no-commit - - --no-report - - --skip-note -- summon [?options] [PATH] - - --branch | -b - - --no-prompt - - --skip-note -- bump [?options] [VERSION] [PATH] - - --branch | -b [BRANCH] - - --no-prompt - - --no-commit - - --no-report - - --registry [REGISTRY] -- new [?options] [PATH] - - --list - - --force | -f - - --no-interactive - - --template | -t [TEMPLATE] -- run [?options] [PATH] - - --sysimage | -J [PATH] - - --threads | -t [?NUMBER_OF_THREADS] - - --procs | -p [?NUMBER_OF_PROCESSES] - - --color [?OPT] - - --verbose | -v -- script - - update [?options] [PATH] - - --verbose | -v - - rm [PATH] - - repl [PATH] -- add [?options] [PACKAGE...] - - --global | -g -- develop | dev [?options] [PACKAGE] - - --global | -g - - --all - - --version | -v -- free [?options] [PACKAGE] - - --global | -g -- gc [?options] - - --global | -g -- precompile [?options] [PACKAGE...] - - --strict - - --global | -g -- remove | rm [?options] [PACKAGE...] - - --global | -g -- status | st [?options] - - --outdated - - --no-diff - - --manifest - - --global | -g -- update | up [?options] [PACKAGE...] - - --global | -g -- why [?options] [PACKAGE] - - --global | -g -- completions [SHELL] -- template - - list - - update - - inspect [?TEMPLATE_NAME] - - --all - - --verbose | -v - +- [Ion website](https://rogerluo.dev/Ion/) +- check `ion --help` for more information in the terminal ## License diff --git a/website/docs/commands/clone.md b/website/docs/commands/clone.md index 011a867..6e3e313 100644 --- a/website/docs/commands/clone.md +++ b/website/docs/commands/clone.md @@ -3,3 +3,10 @@ sidebar_position: 4 --- # Cloning the repository of a package + +- Have you gotten annoyed that cloning a Julia package using git ends up in a folder with `xxxx.jl` by 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 dev command 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 origin to remote upstream and 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!** diff --git a/website/docs/commands/new.md b/website/docs/commands/new.md index 448d5f2..13726ff 100644 --- a/website/docs/commands/new.md +++ b/website/docs/commands/new.md @@ -3,5 +3,46 @@ sidebar_position: 2 --- -# Creating a new project +# 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. + +The following is a project template for a small project: + +```toml +name="project" +description = "A project description" + +[readme] +[project_file] +[src_dir] +[tests] +``` + +and the following is a project template for research packages: + +```toml +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](https://github.com/Roger-luo/ion-templates)! diff --git a/website/docs/commands/pkg.md b/website/docs/commands/pkg.md index 6f24506..6e7c00e 100644 --- a/website/docs/commands/pkg.md +++ b/website/docs/commands/pkg.md @@ -4,4 +4,22 @@ sidebar_position: 1 # Julia Pkg Commands -The Julia package manager is called `Pkg`. It is used to install, update, and remove packages, as well as to manage the versions of packages in your project. The `Pkg` module is part of the standard library and is always available. \ No newline at end of file +The Julia package manager is called `Pkg`. It is used to install, update, and remove packages, as well as to manage the versions of packages in your project. The `Pkg` module is part of the standard library and is always available. + +Ion forwards Julia's Pkg commands in the terminal, e.g + +```sh +> ion add -h +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. diff --git a/website/docs/commands/release.md b/website/docs/commands/release.md index 8b24006..1c67a16 100644 --- a/website/docs/commands/release.md +++ b/website/docs/commands/release.md @@ -2,4 +2,27 @@ sidebar_position: 3 --- -# Release a new version of your project +# 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 + +```sh +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 Ion will also summon JuliaRegistrator directly without asking you to open the browser. + +## Releases + +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`](https://github.com/casey/just) (recommended) or `make`, like what I do here. + +![ion-release-gif-demo](/img/ion.gif) diff --git a/website/docs/commands/script.md b/website/docs/commands/script.md index 4801782..b82ca08 100644 --- a/website/docs/commands/script.md +++ b/website/docs/commands/script.md @@ -2,4 +2,62 @@ --- -# Running Julia scripts with Ion +# Running Julia with Ion + +## Run Julia with local environment `--project` by default + +As for normal scripts, many Julia users want `julia --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 (introduced in next section), `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` | + +**and with shell auto-completion if you have set it up!** + +## Run a standalone script with dependencies + +This is a feature that is supported in many other languages: Single-file scripts that download their dependencies. The lack of this feature has been a gripe from users in the Julia community; Ion solves this pain point with its new script system. + +You can write the following in your Julia script + +```julia +# !/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 + +```sh +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! + +We also have an alternative mode letting you specify UUID, git revision, URL, path, etc, e.g + +```julia +# !/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. diff --git a/website/docs/install.md b/website/docs/install.md index 97314cc..83015bb 100644 --- a/website/docs/install.md +++ b/website/docs/install.md @@ -2,4 +2,44 @@ sidebar_position: 2 --- -# Installation \ No newline at end of file +# Installation + +The installation process is currently a bit manual, but we are working on making +it easier. + +You can download the pre-built binary from the [releases page](https://github.com/Roger-luo/Ion/releases), there is only one binary inside each tarball, you can put it anywhere you want, and add it to your `PATH`. Usually you can just put it in `~/.local/bin` and add `~/.local/bin` to your `PATH`. + +## Install from source + +Ion is written in rust, so you need to have [rust installed](https://www.rust-lang.org/learn/get-started) to build it from source. + +```bash +git clone https://github.com/Roger-luo/Ion.git +cd Ion +cargo install --path . +``` + +Or you can use [`just`](https://github.com/casey/just) + +```bash +just install +``` + +## Optional prerequisites + +- `git`: some Ion commands requires git to be installed, such as using `ion new` + to setup a new project with git repo. +- `julia`: Ion forwards Julia pkg commands to manage current `julia` environment. + If you don't have `julia` installed, Ion will still work, but you won't be able + to use Julia pkg commands. + +## Shell auto-completion + +If you want to have shell auto-completion, after downloading ion, run `ion completions ` to generate the shell completion script, e.g for `oh-my-zsh` you can copy and paste the following + +```sh +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. diff --git a/website/docs/intro.md b/website/docs/intro.md index 2a9079d..a290f68 100644 --- a/website/docs/intro.md +++ b/website/docs/intro.md @@ -4,44 +4,109 @@ sidebar_position: 1 # Intro -Let's discover **Docusaurus in less than 5 minutes**. - -## Getting Started - -Get started by **creating a new site**. - -Or **try Docusaurus immediately** with **[docusaurus.new](https://docusaurus.new)**. - -### What you'll need - -- [Node.js](https://nodejs.org/en/download/) version 16.14 or above: - - When installing Node.js, you are recommended to check all checkboxes related to dependencies. - -## Generate a new site - -Generate a new Docusaurus site using the **classic template**. - -The classic template will automatically be added to your project after you run the command: - -```bash -npm init docusaurus@latest my-website classic -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -The command also installs all necessary dependencies you need to run Docusaurus. - -## Start your site - -Run the development server: - -```bash -cd my-website -npm run start -``` - -The `cd` command changes the directory you're working with. In order to work with your newly created Docusaurus site, you'll need to navigate the terminal there. - -The `npm run start` command builds your website locally and serves it through a development server, ready for you to view at http://localhost:3000/. - -Open `docs/intro.md` (this page) and edit some lines: the site **reloads automatically** and displays your changes. +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. + +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. + +## Commands available + +| Commands | Description | +| ---------------------------- | ------------------------------------------------------------ | +| new [PATH] | Create a new package | +| clone [URL] [PATH] | Clone a package from URL or registry | +| release [VERSION] [PATH] | release a new version of a package | +| bump [VERSION] [PATH] | bump the version of a package | +| summon [PATH] | summon JuliaRegistrator to register the package | +| run [PATH] | Run a script, or start a REPL if no script is given | +| script update/rm/repl [PATH] | script tools | +| add [PACKAGE...] | Add dependencies to current environment | +| remove [PACKAGE...] | Remove dependencies in the current environment [aliases: rm] | +| develop [PACKAGE] | Develop packages in the current environment [aliases: dev] | +| free [PACKAGE] | Free pinned packages in the current environment | +| gc | garbage collect packages not used for a significant time | +| precompile [PACKAGE...] | Precompile all packages in the current environment | +| status | Show the status of the current environment [aliases: st] | +| update [PACKAGE...] | Update the current environment [aliases: up] | +| why [PACKAGE] | show why a package is installed | +| template list/update/inspect | template management | +| completions [SHELL] | generate shell completion scripts | +| auth login/logout | manage Github authentication | + +## Command List + +NB: sub-commands are indicated with bullet points and options are indicated with bullet points plus short or long flags (ie. -f or --flag). +Arguments are listed in square brackets, such as [URL]. A positional arg which is capable of handling multiple arguments is listed with ellipses following the name (eg. [EXAMPLE...]). + +Optional arguments are listed with a `?` before the name; generally speaking, if required arguments are not provided, Ion will ask for them. + +ion + +- auth + - login + - logout +- clone [?options] [URL] [PATH] + - --registry [REGISTRY] +- release [?options] [VERSION] [PATH] + - --branch | -b [?BRANCH] + - --registry [?REGISTRY] + - --no-prompt + - --no-commit + - --no-report + - --skip-note +- summon [?options] [PATH] + - --branch | -b + - --no-prompt + - --skip-note +- bump [?options] [VERSION] [PATH] + - --branch | -b [BRANCH] + - --no-prompt + - --no-commit + - --no-report + - --registry [REGISTRY] +- new [?options] [PATH] + - --list + - --force | -f + - --no-interactive + - --template | -t [TEMPLATE] +- run [?options] [PATH] + - --sysimage | -J [PATH] + - --threads | -t [?NUMBER_OF_THREADS] + - --procs | -p [?NUMBER_OF_PROCESSES] + - --color [?OPT] + - --verbose | -v +- script + - update [?options] [PATH] + - --verbose | -v + - rm [PATH] + - repl [PATH] +- add [?options] [PACKAGE...] + - --global | -g +- develop | dev [?options] [PACKAGE] + - --global | -g + - --all + - --version | -v +- free [?options] [PACKAGE] + - --global | -g +- gc [?options] + - --global | -g +- precompile [?options] [PACKAGE...] + - --strict + - --global | -g +- remove | rm [?options] [PACKAGE...] + - --global | -g +- status | st [?options] + - --outdated + - --no-diff + - --manifest + - --global | -g +- update | up [?options] [PACKAGE...] + - --global | -g +- why [?options] [PACKAGE] + - --global | -g +- completions [SHELL] +- template + - list + - update + - inspect [?TEMPLATE_NAME] + - --all + - --verbose | -v diff --git a/website/static/img/ion.gif b/website/static/img/ion.gif new file mode 100644 index 0000000..18eed1b Binary files /dev/null and b/website/static/img/ion.gif differ