# Artefactsを使い始める

Site [llms.txt](/ja/llms.txt)

---

## アカウント作成

メールアドレスまたはGoogleアカウントが必要です。 [https://app.artefacts.com](https://app.artefacts.com) にアクセスして手続きを進めてください。

## ロボットアプリケーションテスト実行のための推奨システム要件

Artefactsクライアントは比較的軽量であるため、ハードウェア要件はArtefacts自体ではなく、実行しようとするシミュレーションに基づきます。

私たちはROS2がサポートしているものをサポートしています：

* Ubuntu 22.04 (ROS2 Humbleプロジェクト向け推奨)
* Ubuntu 24.04 (ROS2 Jazzyプロジェクト向け推奨)

MacOSまたはWindowsでは、Ubuntu 22.04または24.04を搭載した仮想マシンの使用をお勧めします。

シミュレーション実行のための一般的な推奨事項：

* 最低8GのRAM（シミュレーションの複雑さによる）
* 最低4CPUコア（シミュレーションとロボットアプリケーションの複雑さによる）
* 少なくとも20Gの空きディスク容量（シミュレーション資産、rosbagsなどを扱うため）
  
## CLIインストール

Python 3.10以上を使用して：

```bash
pip install artefacts-cli
```

### 代替インストール方法（pipx）

[pipx](https://pipx.pypa.io/stable/) を使用すると、アプリケーションを分離された環境にインストールしつつ、シェルのどこからでもアクセスできるようになります。これはPython 3.12のより厳格な環境分離のために役立つ場合があります。

Artefactsは以下のようにインストールできます：

```
sudo apt install pipx
pipx ensurepath
pipx install artefacts-cli
```

### インストール後の確認

`artefacts doctor` を実行して、すぐに利用可能なArtefacts機能の概要を確認してください。

このコマンドはコア機能を確認し、オプションの推奨設定を確認し、ロボティクスフレームワーク（ROS）のユーザー向けの追加情報を提供します。

詳細については、[CLI doctorリファレンス](/clireference/#doctor)をご覧ください。

Doctorはシェル補完のインストールを推奨します：

```bash
artefacts completion install
```

これにより、bash、zsh、fishで`artefacts`コマンドのタブ補完が有効になります。
Linux、MacOS、およびWindowsでPowerShellの実験的サポートがあります。
詳細については、[シェル補完コマンドリファレンス](/clireference/#completion)をご覧ください。

### プロジェクト用のPython仮想環境を使用する

`artefacts run`（`--in-container` を使用しない場合）は、現在のシェル内でテストコマンドを直接実行します。Python環境の作成、アクティブ化、管理は行いません。プロジェクト自体の依存関係（テスト要件、シミュレーターのバインディングなど）が仮想環境にある場合は、`artefacts run` を呼び出す前にその仮想環境をアクティブ化してください：

```bash
source venv/bin/activate
artefacts run my_job
```

> [!NOTE]
> `--in-container` モードにはこの問題はありません。プロジェクトの `Dockerfile` からビルドされたDockerイメージ内でジョブをビルド・実行するため、シェルで何がアクティブになっているかに関わらず、独自の自己完結型のPython環境を持ちます。

### ROSユーザー向け

仮想環境の使用をお勧めしますが、仮想環境とROS2の併用は複雑な場合があることに注意してください。ROSがソースされると、ROSの独自のPythonパッケージディレクトリを参照する`PYTHONPATH` が存在しない場合は作成されます。

そのため、仮想環境のsite-packagesディレクトリを含むように `PYTHONPATH` をエクスポートする必要がある可能性が高いです：

```
export PYTHONPATH=$PYTHONPATH:/home/[USER]/<myproject>/venv/lib/python3.10/site-packages
```

### ROS2 Jazzyユーザー向け（Ubuntu 24とPython 3.12）

Ubuntu 24でROS 2 Jazzy（Python 3.12を使用）を使用し、Artefacts CLI（またはpipや `apt install python3-xxx`でインストールされた他のPythonパッケージ) をROSパッケージと一緒に実行したい場合、Python 3.12のより厳格な環境分離により追加の課題に遭遇する可能性があります。

ArtefactsをVirtualEnvでインストールする場合でもpipxでインストールする場合でも、仮想環境を使用している場合はそれに加えて、システムPythonパッケージディレクトリをPYTHONPATHに追加することを強くお勧めします：

```bash
export PYTHONPATH=$PYTHONPATH:/usr/lib/python3/dist-packages
```

> [!NOTE]
> Docker で `jazzy` ベースイメージ（例：`public.ecr.aws/artefacts/ros2:jazzy-harmonic`）を使用してテストを実行する場合、仮想環境と `PYTHONPATH` 環境変数は既に ROS2 Jazzy で正しく動作するように設定されています。これにより、ROS をソースした後でも pip でインストールされたパッケージが利用可能になります。Python 環境の追加設定は不要です。

## 使用リファレンス

CLIの使用方法については、 [CLIリファレンス](/clireference)

`artefacts.yaml` ファイルの設定については、 [設定ファイル構文](/configuration/artefacts-yaml) を参照してください。


## チュートリアルとサンプルプロジェクト

ROS2でテストを作成する方法については、 [ros-2-simulation-workflowsリポジトリ](https://github.com/art-e-fact/ros2-simulation-workflows)を参照してください。


サンプルプロジェクト：

* 最小限の例： [Example Turlesim](https://github.com/art-e-fact/example-turtlesim)
* ロボットナビゲーション： [Nav2 + Gazeboデモ](https://github.com/art-e-fact/navigation2_ignition_gazebo_example)

## 一般的なトラブルシューティング

開発中に役立つと思われる、ROS（特にテスト）での作業に関する一般的な [トラブルシューティング](/troubleshooting) セクションがあります。