第2章：環境構築と動作確認（WSL2 + Dockerベース完全自習ガイド）

本章では、Windows 11 PC上に世界標準のオープンソース半導体設計ラボを構築します。WSL2（Windows Subsystem for Linux）とDocker Desktopを組み合わせた環境を構築します。コマンドを1行ずつ手作業で打ち込みながら進めましょう。

※本章は現行版（2025年シャトル ttsky25b / LibreLane 3.0.3）に準拠して全面改訂しています。 Tiny Tapeoutのローカル・ハードニング手順は2024年以降に大きく変わり、旧来の pip install tinytapeout や tt harden という単独コマンドは現在のフローには存在しません。本章の手順は、公式ガイド Hardening Tiny Tapeout Projects Locally に対応しています。

2.0 はじめに ― この章の歩き方と準備

環境構築は、本講座の中で最もつまずきやすい場所だと、本講座は考えています。ツールが多く、待ち時間も長く、エラーメッセージも英語で出ます。そこで本節では、手を動かす前に「どこまでを本章で扱うか」「詰まったときにどう動くか」「自分のPCで足りるか」を先に整理しておきます。ここを読んでおくと、このあとの作業で迷子になりにくくなります。

# Ubuntu（WSL2）側で、使えるメモリの合計を見る
free -h

# Windowsの物理メモリ総量を見る（PowerShellで実行。GB単位で表示）
(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB

2.1 【Step 1】WSL2およびUbuntu 24.04 LTSの完全導入

まずはWindows側にLinux環境の土台を作ります。

1. Windowsのスタートメニューを右クリックし、「ターミナル（管理者）」または「PowerShell（管理者）」を選択して起動します。一般ユーザー権限では仮想化機能の有効化ができません。
2. 起動した画面に、以下のコマンドを正確に入力してEnterキーを押します。

   wsl --install -d Ubuntu-24.04

   ※ Ubuntu 22.04でも動作しますが、現行手順は Python 3.11以降 が前提です。24.04 LTSなら標準のPythonが3.12なので確実です。22.04を使う場合はPythonのバージョンに注意してください（python3 --versionで確認）。

3. 画面に進捗が表示され、100%になるまで待ちます。完了したらPCを必ず再起動してください。再起動を行わないと、WSL2の仮想化機能が有効化されません。
4. 再起動後、自動的に黒いウィンドウ（Ubuntuのセットアップ画面）が立ち上がります。指示に従ってユーザー名（例：student）とパスワードを設定します。文字を入力しても画面には表示されませんが、内部では入力されています。

2.2 【Step 2】Docker Desktop for Windows の完全連携設定

次に、ツールの実行エンジンとなるDockerをWindows側に入れます。LibreLaneは内部でコンテナを起動して各EDAツールを実行するため、Dockerは必須です。

1. Docker公式ページからインストーラーをダウンロードして実行します。インストール時のオプション画面で、「Use the WSL 2 based engine (recommended)」に必ずチェックが入っていることを確認してください。
2. インストールが完了したらDocker Desktopを起動し、右上にある歯車アイコン（Settings）をクリックします。
3. 左メニューから [Resources] ➔ [WSL integration] を選択します。
4. 「Enable integration with my default WSL distro」にチェックを入れ、その下にある 「Ubuntu-24.04」のトグルスイッチを「ON」 にして、右下の [Apply & restart] を押します。

【補足】Ubuntuターミナルの開き方とコピペ のやり方

手順書には「Ubuntuのターミナルで次を実行」と書かれていても、そもそもどの黒い画面を開けばいいのか、コピーした手順をどう貼り付けるのかが分からず止まってしまう ― これは初学者にとても多いつまずきだと、本講座は考えています。技術的には些細に見えても、ここで止まると先に進めないので、丁寧に確認しておきます。

(1) 正しいUbuntuのターミナルを開く

• 方法A（おすすめ）： スタートメニューから「ターミナル」を起動し、上部のタブの横にある下向き「∨」をクリックして、一覧から 「Ubuntu-24.04」 を選びます。
• 方法B： スタートメニューで「Ubuntu 24.04 LTS」を直接探して起動します。

(2) いま開いているのがUbuntuか、PowerShellかを見分ける

同じような黒い画面でも、中身が違うことがあります。プロンプト（入力位置の手前に出ている文字）で見分けられます。

  student@PC-NAME:~$            ← 末尾が :~$  → Ubuntu（これが正解。ここで作業する）

  PS C:\Users\you>             ← 先頭が PS、C:\... → PowerShell（場所違い。ここでは作業しない）

手順書のコマンドを打っているのに「コマンドが見つからない」と言われるときは、そもそもPowerShell側に打ち込んでしまっていることがよくあります。まずプロンプトを見て、自分が今どちらにいるかを確認してください。

(3) コピーした手順を貼り付ける

• 新しいWindows Terminal（方法A）では、貼り付けは Ctrl + Shift + V、または右クリックです。普段の Ctrl + V とは少し違う点に注意してください。
• 旧式の黒いウィンドウ（コンソール）でうまく貼れない場合は、ウィンドウ左上のアイコンを右クリック → 「プロパティ」 → 「簡易編集モード」をオンにすると、右クリックで貼り付けられるようになります。

(4) 手順書の # で始まる行は、打ち込まなくてよい

本章のコマンド例には # で始まる行が出てきます。これは人間向けの「コメント（説明）」で、コンピュータへの命令ではありません。コピーして一緒に貼り付けても無視されますが、意味を理解する手がかりとして読んでおくと、何をしているかが分かります。

(5) 作業を始める時は、まずDocker Desktopの起動から

前節の [Apply & restart] の後、「次に何をすればいいの？」と迷いやすい場所です。結論としては、作業を始める際は、Ubuntuのターミナルを開くより先に、まずWindows側でDocker Desktopを起動しておくのが安全です。LibreLaneはDockerの上で動くため、Dockerが起きていないと後の工程で止まります。起動して少し待ち、次のコマンドで疎通を確認できます。

# Dockerがちゃんと動いているか確認（成功すれば歓迎メッセージが出る）
docker run hello-world

2.3 【Step 3】WSL2内部での依存パッケージ一括導入

ここからの作業は、すべてWSL2（Ubuntu）のターミナル画面で行います。以下のコマンドを1行ずつ実行してください。

# 1. パッケージリストを更新し、古いコンポーネントを一括アップデート
sudo apt update && sudo apt upgrade -y

# 2. 設計管理に必須のGit、Python3、仮想環境生成パッケージ、ビルド用基本ツール、
#    およびハーデンのPNG出力で必要になる cairo ライブラリを導入
sudo apt install -y git python3 python3-pip python3-venv build-essential libcairo2 libcairo2-dev

# 3. WSL2内のLinuxユーザーが、管理者権限なしでDockerを操作できるように権限を付与
sudo usermod -aG docker $USER

# 4. 上記の権限変更をシステムに反映させるため、一度セッションを閉じます
exit

OSError: no library called "cairo-2" was found

※注意： ウィンドウが一度閉じますので、もう一度スタートメニューから「Ubuntu 24.04 LTS」を起動して新しいウィンドウを開いてください。

新しく開いたUbuntuの画面で、まずPythonのバージョンとDockerの動作を確認します。

# いま自分がどこにいるか（カレントディレクトリ）を確認
pwd

# Pythonが3.11以降であることを確認（現行フローの前提条件）
python3 --version

# Dockerの動作テスト
docker run hello-world

Dockerのテストで画面に Hello from Docker! ... と出力されれば成功です。

2.4 【Step 4】公式プロジェクトテンプレートの取得と tt-support-tools の配置

現行フローでは、(1) プロジェクトのテンプレートを取得し、(2) その中に「Tiny Tapeoutのビルドツール群（tt-support-tools）」を tt/ というサブディレクトリとしてクローンします。本章では、公式ガイドが採用しているサンプル（ttsky25b-factory-test）をそのまま使って環境を検証します。

※テンプレートについて： 自分で新しいプロジェクトを始める場合は ttsky-verilog-template を使います（第3章以降で扱います）。本章ではまず「確実に通る既知のサンプル」で環境を固めるため、公式ガイドと同じ factory-test を使います。なお、旧版で使われていた tt09-verilog-template は世代が古いため、新規設計には現行シャトル ttsky25b 系を使ってください。

# 1. 公式ガイドのサンプルプロジェクトをホームディレクトリにクローン
git clone https://github.com/TinyTapeout/ttsky25b-factory-test ~/factory-test

# 2. プロジェクト内に入り、ビルドツール tt-support-tools を tt/ ディレクトリとしてクローン
cd ~/factory-test
git clone https://github.com/TinyTapeout/tt-support-tools tt

2.5 【Step 5】Python仮想環境の作成と依存パッケージの導入

専用の隔離されたPython仮想環境（venv）を作り、ビルドツールが要求するパッケージ群を導入します。

# 1. 仮想環境専用のディレクトリを作成して初期化
mkdir ~/ttsetup
python3 -m venv ~/ttsetup/venv

# 2. 仮想環境を有効化（成功するとプロンプトの左端に (venv) と表示されます）
source ~/ttsetup/venv/bin/activate

# 3. tt-support-tools が要求する依存パッケージを一括インストール
pip install -r ~/factory-test/tt/requirements.txt

  (venv) student@PC:~/factory-test$    ← 左端に (venv) あり → 正しい（この状態で pip する）

  student@PC:~/factory-test$           ← (venv) なし → 無効。先に下のコマンドで戻す

source ~/ttsetup/venv/bin/activate

2.6 【Step 6】環境変数の設定とLibreLaneのインストール

使用するPDK（プロセス設計キット）とLibreLane本体のバージョンを環境変数で指定し、LibreLaneをインストールします。本講座ではSkyWater 130nm（sky130A）を使います。

# 1. PDKの格納先・種類・LibreLaneのバージョンを指定（SkyWater 130nm の場合）
export PDK_ROOT=~/ttsetup/pdk
export PDK=sky130A
export LIBRELANE_TAG=3.0.3

# 2. 指定したバージョンのLibreLane本体をインストール
pip install librelane==$LIBRELANE_TAG

※「LibreLane」とは： 旧称 OpenLane 2 がリネームされたもので、Yosys（論理合成）・OpenROAD（配置配線）・Magic／Netgen（物理検証）といったオープンソースEDAツール群を1本のフローとして束ねる司令塔です。Pythonモジュールとして提供され、内部でDockerコンテナを起動して各ツールを実行します。

   あなたが打つコマンド
        │
        ▼
  ┌──────────────────────────┐
  │  tt（tt-support-tools）   │  ← 運転席。TinyTapeout用に呼びやすくした窓口
  │   ./tt/tt_tool.py --harden│
  └────────────┬─────────────┘
               │ 内部で呼び出す
               ▼
  ┌──────────────────────────┐
  │  librelane（本体エンジン）│  ← 物理設計を実際に動かす中身（pipで入れたもの）
  │   Yosys / OpenROAD / ...  │
  └──────────────────────────┘

※バージョンについて： PDK や LIBRELANE_TAG の最新の推奨値は将来変わる可能性があります。最新値は公式の tt-gds-action の action.yml（librelane-version の default 値）で確認できます。

2.7 【Step 7】サンプル設計のハードニング（Smoke Test）

環境構築の最終仕上げとして、サンプル設計を実際にハードニング（RTL→GDSII変換）します。必ず (venv) が表示され、かつ 2.6 の環境変数が設定済みの状態で、プロジェクトのルートに移動してから実行してください。

  実体             焼き物            3Dプリンタ
 ───────────────────────────────────────────────────────────
  RTL(Verilog)     やわらかい粘土     作りたい物のアイデア
  サンプル設計      焼く前の完成模型   完成済みCADモデル
  LibreLane+PDK    窯 ＋ 窯の規格     CAD/スライサ ＋ プリンタ仕様
  ★ハーデン        図面を仕上げる処理 ★STLを書き出すまでの全自動処理
  ★GDS(最終データ) 器を作る型紙/図面  ★STLファイル
  製造(工場)        実際に焼いて器に   実際に積層印刷して物体化

# プロジェクトのルートに移動
cd ~/factory-test

# 1. LibreLane用の設定ファイルを生成
./tt/tt_tool.py --create-user-config

# 2. ローカルでハードニングを実行（Dockerが起動している必要があります）
./tt/tt_tool.py --harden

# 3. 合成・クロックに関する警告がないかをチェック（推奨）
./tt/tt_tool.py --print-warnings

ConfigFileError: Could not find configuration file src/user_config.{json}

コンテナが自動起動し、内部でフローの各ステップ（論理合成→フロアプラン→配置→クロックツリー合成→配線→物理検証）が順に進みます。最終的にエラーなく完了し、runs/ 以下に成果物が生成されれば成功です。

[INFO] Synthesis (Yosys) ...               <-- RTLを論理ゲートへ変換
[INFO] Floorplan (OpenROAD) ...            <-- チップ外形・電源格子を配置
[INFO] Placement (OpenROAD) ...            <-- 標準セルを自動敷き詰め
[INFO] Clock Tree Synthesis (OpenROAD) ... <-- クロック遅延を均等化
[INFO] Routing (OpenROAD) ...              <-- 金属層で自動3次元配線
[INFO] Sign-off: DRC (Magic) / LVS (Netgen) ... <-- 物理検証
[INFO] Flow complete.

もしメモリ不足で止まったら ― WSL2でのメモリの増やし方

大きな設計（とくに第5章のRISC-Vコア）では、ハーデン中のメモリ消費が増え、途中で止まることがあります。ここで注意したいのは、WSL2を使う本構成では、メモリの調整は「Docker Desktopの設定」ではなく「WSL2側の設定（.wslconfig）」で行うという点です。

※よくある誤解： 「Docker Desktopの設定画面にメモリのスライダーが出てこない／動かしても効かない」という声がありますが、WSL2バックエンドではスライダーが出ない・効かないのが正常です。Dockerが使えるメモリは、WSL2に割り当てられたメモリで決まるためです。

手順は次のとおりです。まず、いま使えるメモリ量を確認します。

# Ubuntu（WSL2）側で、使えるメモリの合計を確認（Mem: 行の total を見る）
free -h

total が十分（たとえば16GiB前後以上）あるなら、この調整は不要です。4GiB未満など明らかに少ないときだけ、次の調整を行います。Windowsのユーザーフォルダ（%UserProfile%、たとえば C:\Users\あなたの名前）に .wslconfig というファイルを作り、次の内容を書きます。

[wsl2]
memory=8GB
processors=4

保存したら、PowerShell（管理者でなくてよい）で一度WSL2を停止し、Ubuntuを開き直して反映を確認します。

# PowerShellでWSL2をいったん停止（次にUbuntuを開くと新しい設定で起動する）
wsl --shutdown

# Ubuntuを開き直して、割り当てが反映されたか確認
free -h

Windowsの物理メモリ総量そのものを確認したいときは、PowerShellで次を使うのが確実です。

# 物理メモリ総量をGB単位で表示（確実に動く方法）
(Get-CimInstance Win32_ComputerSystem).TotalPhysicalMemory / 1GB

※日本語版Windowsでは、systeminfo | findstr /C:"Total Physical Memory" は項目名が日本語のため空になることがあります。findstr /C:"物理メモリ" も版によっては空になる場合があるため、上記の Get-CimInstance を使うのが確実です。

※「十分積んでいれば、この調整は不要」： 参考までに、執筆者の環境では物理メモリ96GB・WSL2への割り当て46GBで、メモリ対策は不要でした。free -h で total に余裕があれば、.wslconfig はそもそも作らなくて構いません。逆に言えば、困ったときだけ開く逃げ道として覚えておけば十分です。

2.8 【演習】生成された成果物構造の探検

ハードニングが完了すると、成果物は runs/<RUN_TAG>/ 以下に生成されます。Tiny Tapeoutのフローでは、この RUN_TAG は既定で wokwi です（プロジェクトの由来に関係なくこの名前が使われます）。中身を確認してみましょう。

# 実行結果のルートを確認
ls -la ./runs/wokwi/

# 最終GDS（製造に送られる最終形状データ）を確認
ls -la ./runs/wokwi/final/gds/

# ゲートレベル・ネットリスト（電源ピン付き）を確認
ls -la ./runs/wokwi/final/pnl/

• runs/wokwi/final/gds/ : 本物のシリコンに焼き付けるための最終形状データ（.gds完成品）が格納されています。
• runs/wokwi/final/pnl/ : 電源ピン付きゲートレベル・ネットリスト（*.pnl.v）。ゲートレベル・シミュレーションで使います。
• runs/wokwi/<各ステップのサブフォルダ>/ : タイミング解析や面積などのレポートは、各フローステップごとのサブフォルダ（例：STA関連のステップ）に分散して出力されます。レポートの正確な所在は第4章で扱います。

  runs/wokwi/
   ├─ 01-verilator-lint/      ← Verilogの文法チェックの記録
   ├─ 02-checker-.../         ← 各種チェックの記録
   ├─ 05-yosys-.../           ← 論理合成（Yosys）の記録
   ├─ ...（合成→配置→CTS→配線→検証 と続く）...
   └─ final/                  ← 最終成果物（gds / pnl）
      ├─ gds/  → 製造用の最終データ（.gds）
      └─ pnl/  → 電源ピン付きネットリスト（.pnl.v）

  工程（止まる場所）        転ぶときの典型的な症状        直し方の方向
 ──────────────────────────────────────────────────────────────────────────
  lint（Verilator）        文法の書き間違い              Verilog記述を直す
  yosys（論理合成）        回路として成立しない論理       記述の論理を見直す
  Placement / Congestion   配置が密すぎて配線できない     密度を下げる（PL_TARGET_DENSITY_PCT）
  STA / slack              クロックに間に合わない         クロック周期を緩める
  DRC・LVS                 ルール違反／接続の不一致       該当箇所を修正する
  全工程パス               （成功）                       final/gds/ にGDSが出る

※旧版からの主な変更点（要点）： 旧 runs/tt_top/results/final/gds/ という固定パスは現行版には存在しません。現行では runs/wokwi/final/... 配下に成果物がまとまります。レポートも reports/ 直下ではなく各ステップフォルダに分かれます。

※GUIで眺めるときの注意： KLayoutなどのGUIを起動すると、初回は表示までに1〜2分かかることがあります。無反応に見えても Ctrl + C で止めないでください（止めてもGDS自体には影響しませんが、起動し直しになります）。WSLでGUIが開かない場合の補足（WSLgや xhost +local:docker）は、第4章・第6章で扱います。

2.9 作業の中断と再開 ― 続きをやるときの「3点おまじない」

環境構築やハーデンは時間がかかるため、「今日はここまで」と中断したり、別の日に再開したりすることが必ずあります。ここでつまずく人が多いので、安全な止め方と、再開のやり方を独立した節としてまとめておきます。

(1) 安全な止め方

• 基本は、完走を待つ。 ハーデンが走っている最中は、できるだけ最後まで待つのが安全です。
• どうしても止めたいときだけ Ctrl + C。 中途半端な runs が残ることがありますが、もう一度ハーデンし直せば上書きされるので、致命的ではありません。

(2) 一日の終わり方

作業を終えるときは、ウィンドウを閉じる／PCを落とすだけで構いません。作成済みのGDS（runs/wokwi/...）は、ディスク上に残っているので消えません。安心して終了してください。

(3) 再開チェックリスト（毎回これをやる）

別の日に再開するときは、次の5つを順に行います。venvと export はウィンドウを閉じると消えるため、毎回これが必要になります。

# ① まずWindows側でDocker Desktopを起動しておく（最初に）

# ② プロジェクトのフォルダへ移動
cd ~/factory-test

# ③ 仮想環境を有効化（左端に (venv) が出ることを確認）
source ~/ttsetup/venv/bin/activate

# ④ 環境変数3行を再投入（export はウィンドウを閉じると消えるため）
export PDK_ROOT=~/ttsetup/pdk
export PDK=sky130A
export LIBRELANE_TAG=3.0.3

# ⑤ Dockerが動いているか疎通確認
docker run hello-world

※なぜ毎回必要なのか： 仮想環境（venv）と export した環境変数は、ウィンドウを閉じると消える性質があるためです。毎回打ち直すのが面倒なら、~/.bashrc に書いておけば自動で読み込ませることもできます（任意・上級者向け。慣れてからで構いません）。

pwd                  # ① 今どこにいる？（場所の確認）
                     # ② → (venv) が左端に出ているか？（仮想環境の確認）
echo $LIBRELANE_TAG  # ③ 3.0.3 と表示されるか？（環境変数の確認）