diff --git a/README.md b/README.md index 83a53da4f..f7e07d2a2 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,16 @@ For engineers who want more confidence than spreadsheets and ad-hoc scripts prov ## Quickstart -Install the CLI with [Rust](https://rustup.rs/): +Install the prebuilt CLI (see the [installation guide](https://graphcal.org/docs/en/installation/) for package managers and GitHub Actions): ```sh -# The version flag is needed while Graphcal is a pre-release. -cargo install graphcal --version '^0.0.1-alpha' --locked +# macOS and Linux +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/graphcal-lang/graphcal/releases/latest/download/graphcal-installer.sh | sh +``` + +```powershell +# Windows +powershell -ExecutionPolicy Bypass -c "irm https://github.com/graphcal-lang/graphcal/releases/latest/download/graphcal-installer.ps1 | iex" ``` Save [`rocket.gcl`](tests/fixtures/valid/rocket.gcl), the file shown above, then run: diff --git a/docs/en/installation.md b/docs/en/installation.md index cb1235825..d631bdf34 100644 --- a/docs/en/installation.md +++ b/docs/en/installation.md @@ -4,24 +4,47 @@ icon: material/download # Installation -## Requirements +Graphcal is a single command-line program, `graphcal`. Prebuilt binaries are available for Linux (x86_64, ARM64), macOS (Intel, Apple Silicon), and Windows (x86_64). -- Rust stable toolchain (1.95 or later) +## Install with the installer script -If you don't have Rust installed, get it from [rustup.rs](https://rustup.rs/). +On macOS and Linux: -## Install from crates.io +```bash +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/graphcal-lang/graphcal/releases/latest/download/graphcal-installer.sh | sh +``` + +On Windows (PowerShell): + +```powershell +powershell -ExecutionPolicy Bypass -c "irm https://github.com/graphcal-lang/graphcal/releases/latest/download/graphcal-installer.ps1 | iex" +``` + +Open a new terminal afterwards so that `graphcal` is on your `PATH`. To update Graphcal, run the same command again. + +## Install with a package manager + +While Graphcal is a pre-release, these commands need an explicit version. Replace `` with a version from the [releases page](https://github.com/graphcal-lang/graphcal/releases), such as `0.0.1-alpha.35`. + +### cargo-binstall + +[cargo-binstall](https://github.com/cargo-bins/cargo-binstall) downloads the prebuilt binary: ```bash -cargo install graphcal --version '^0.0.1-alpha' --locked +cargo binstall graphcal@ ``` -The explicit version requirement is necessary while Graphcal is published as a pre-release. This downloads the latest compatible Graphcal release from [crates.io](https://crates.io/crates/graphcal), builds it, and installs the `graphcal` binary to `~/.cargo/bin/`. +### cargo install -## Build from a source checkout +`cargo install` builds Graphcal from [crates.io](https://crates.io/crates/graphcal). It requires Rust 1.95 or later, which you can get from [rustup.rs](https://rustup.rs/): -Unlike a crates.io installation, building the CLI from a checkout also builds its -embedded browser engine. Install these prerequisites first: +```bash +cargo install graphcal@ --locked +``` + +## Build from source + +Building from a source checkout requires these tools: - The Rust toolchain pinned in `rust-toolchain.toml`, managed by rustup. - Its `wasm32-unknown-unknown` target (`rustup target add wasm32-unknown-unknown` @@ -31,21 +54,13 @@ embedded browser engine. Install these prerequisites first: - Binaryen's `wasm-opt` on `PATH`. CI uses Binaryen 117; prebuilt distributions are available from [Binaryen releases](https://github.com/WebAssembly/binaryen/releases/tag/version_117). -Then run the usual command: +Then build as usual: ```bash cargo build ``` -The CLI automatically builds and embeds the browser engine. The first build -can take longer because it compiles both native and Wasm code. `cargo check`, -Clippy, and editor checks can also trigger this build. - -For an offline source build, prefetch dependencies and set `CARGO_NET_OFFLINE=true`. - -Published crate archives already contain the verified engine; **crates.io users -do not need these additional tools**. Report artifacts remain self-contained and -work without a network connection. +The first build takes longer than usual. `cargo check` and Clippy also need these tools. ## Verify Installation @@ -54,7 +69,34 @@ graphcal --version # graphcal (commit: ) ``` -The commit suffix is shown when the build can determine the source commit. +## Use in GitHub Actions + +The [`setup-graphcal`](https://github.com/graphcal-lang/setup-graphcal) action installs `graphcal` on a GitHub Actions runner. This workflow checks the `.gcl` files and evaluates a model on each push and pull request: + +```yaml +name: Graphcal + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: graphcal-lang/setup-graphcal@v1 + with: + version: 0.0.1-alpha.35 + - run: graphcal check + - run: graphcal eval model.gcl +``` + +The job fails when an assertion fails. Graphcal still changes between alpha releases, so pin `version` to keep the results reproducible. See the [action's README](https://github.com/graphcal-lang/setup-graphcal#readme) for other options. ## Editor Setup diff --git a/docs/ja/installation.md b/docs/ja/installation.md index b3f534dca..5d838fa82 100644 --- a/docs/ja/installation.md +++ b/docs/ja/installation.md @@ -4,48 +4,63 @@ icon: material/download # インストール { #installation } -## 要件 { #requirements } +Graphcal は `graphcal` というコマンドラインプログラム 1 つで動きます。Linux (x86_64、ARM64)、macOS (Intel、Apple Silicon)、Windows (x86_64) 向けにビルド済みバイナリを配布しています。 -- Rust stable ツールチェーン (1.95 以降) +## インストーラスクリプトでインストールする { #install-with-the-installer-script } -Rust がインストールされていない場合は、[rustup.rs](https://rustup.rs/) から入手してください。 +macOS と Linux では次のコマンドを実行します。 -## crates.io からインストールする { #install-from-cratesio } +```bash +curl --proto '=https' --tlsv1.2 -LsSf https://github.com/graphcal-lang/graphcal/releases/latest/download/graphcal-installer.sh | sh +``` + +Windows では PowerShell で次のコマンドを実行します。 + +```powershell +powershell -ExecutionPolicy Bypass -c "irm https://github.com/graphcal-lang/graphcal/releases/latest/download/graphcal-installer.ps1 | iex" +``` + +インストールが終わったら、新しいターミナルを開くと `graphcal` を使えます。アップデートするときも、同じコマンドをもう一度実行します。 + +## パッケージマネージャでインストールする { #install-with-a-package-manager } + +Graphcal はまだプレリリースなので、以下のコマンドではバージョンを明示する必要があります。`` は [リリース一覧](https://github.com/graphcal-lang/graphcal/releases) にあるバージョン (`0.0.1-alpha.35` など) に置き換えてください。 + +### cargo-binstall { #cargo-binstall } + +[cargo-binstall](https://github.com/cargo-bins/cargo-binstall) はビルド済みバイナリをダウンロードします。 ```bash -cargo install graphcal --version '^0.0.1-alpha' --locked +cargo binstall graphcal@ ``` -Graphcal がプレリリースとして公開されている間は、明示的なバージョン指定が必要です。このコマンドは [crates.io](https://crates.io/crates/graphcal) から互換性のある最新の Graphcal リリースをダウンロードしてビルドし、`graphcal` バイナリを `~/.cargo/bin/` にインストールします。 +### cargo install { #cargo-install } -## ソースチェックアウトからビルドする { #build-from-a-source-checkout } +`cargo install` は [crates.io](https://crates.io/crates/graphcal) のソースから Graphcal をビルドします。Rust 1.95 以降が必要です。Rust は [rustup.rs](https://rustup.rs/) から入手できます。 -crates.io からのインストールとは異なり、チェックアウトから CLI をビルドすると、 -組み込みのブラウザーエンジンもビルドされます。まず、次の前提条件をインストールしてください: +```bash +cargo install graphcal@ --locked +``` -- rustup で管理される、`rust-toolchain.toml` に固定された Rust ツールチェーン。 +## ソースからビルドする { #build-from-source } + +リポジトリをチェックアウトしてビルドするには、次のツールが必要です。 + +- `rust-toolchain.toml` で固定した Rust ツールチェーン (rustup で管理) - その `wasm32-unknown-unknown` ターゲット (リポジトリのルートで - `rustup target add wasm32-unknown-unknown` を実行)。 -- **`Cargo.lock` で解決された `wasm-bindgen` のバージョン**に一致する `wasm-bindgen-cli`: - `cargo install wasm-bindgen-cli --version --locked`。 -- `PATH` 上にある Binaryen の `wasm-opt`。CI は Binaryen 117 を使用しています。ビルド済みの配布物は - [Binaryen releases](https://github.com/WebAssembly/binaryen/releases/tag/version_117) から入手できます。 + `rustup target add wasm32-unknown-unknown` を実行) +- **`Cargo.lock` で解決された `wasm-bindgen` と同じバージョン**の `wasm-bindgen-cli` + (`cargo install wasm-bindgen-cli --version --locked` でインストール) +- `PATH` 上にある Binaryen の `wasm-opt`。CI は Binaryen 117 を使っています。ビルド済みのものは + [Binaryen のリリース](https://github.com/WebAssembly/binaryen/releases/tag/version_117) から入手できます。 -その後、通常のコマンドを実行します: +ツールを揃えたら、通常どおりビルドします。 ```bash cargo build ``` -CLI はブラウザーエンジンを自動的にビルドして埋め込みます。初回ビルドは、 -ネイティブコードと Wasm コードの両方をコンパイルするため時間がかかることがあります。 -`cargo check`、Clippy、エディターのチェックでも、このビルドが実行されることがあります。 - -オフラインでソースビルドを行うには、依存関係を事前に取得し、`CARGO_NET_OFFLINE=true` を設定してください。 - -公開されているクレートアーカイブには検証済みのエンジンがすでに含まれているため、**crates.io のユーザーは -これらの追加ツールを必要としません**。レポートの成果物は自己完結したままであり、 -ネットワーク接続なしで動作します。 +初回のビルドは通常より時間がかかります。`cargo check` と Clippy を実行するときも、これらのツールが必要です。 ## インストールの確認 { #verify-installation } @@ -54,7 +69,34 @@ graphcal --version # graphcal (commit: ) ``` -コミットのサフィックスは、ビルドがソースのコミットを特定できる場合に表示されます。 +## GitHub Actions で使う { #use-in-github-actions } + +[`setup-graphcal`](https://github.com/graphcal-lang/setup-graphcal) アクションを使うと、GitHub Actions のランナーに `graphcal` をインストールできます。次のワークフローは、push と pull request のたびに `.gcl` ファイルをチェックし、モデルを評価します。 + +```yaml +name: Graphcal + +on: + push: + branches: [main] + pull_request: + +permissions: + contents: read + +jobs: + check: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + - uses: graphcal-lang/setup-graphcal@v1 + with: + version: 0.0.1-alpha.35 + - run: graphcal check + - run: graphcal eval model.gcl +``` + +アサーションが失敗すると、ジョブも失敗します。alpha 版の間はリリースごとに Graphcal の仕様が変わるので、`version` を固定して結果を再現できるようにしてください。そのほかの設定は[アクションの README](https://github.com/graphcal-lang/setup-graphcal#readme) を参照してください。 ## エディターのセットアップ { #editor-setup }