Bunの–compileで実行ファイルを作る方法と大きさ

​​Bun​CLI,TypeScript

bun build --compile を使うと、TypeScript や JavaScript のプログラムを、そのまま実行できる1つのファイルにできます。Bun の実行環境もいっしょに入るので、配った先に Bun や Node.js、node_modules がなくても動きます。

自作の CLI ツールを Bun を入れていない人にも渡したい、サーバーにファイルを1つ置くだけで動かしたい、といった場面で使えます。作り方と、できたファイルの大きさを、検証環境で実際に測りました。

補足

検証環境は Ubuntu 24.04(x86_64、glibc 2.39)、Bun 1.4.4 です。Linux x64 向けに作った実行ファイルだけを、この環境で実行しました。macOS・Windows・arm64 向けに作ったファイルは、作るところと大きさまでで、それぞれの OS では動かしていません。macOS でのコード署名、Windows のアイコンなどの設定、--asset などによるファイルの埋め込みも試していません。公式ドキュメントは、検証に使った版(タグ bun-v1.4.4)の元ファイルを GitHub で確認し、リンクもそこに張っています。

Hello world を実行ファイルにすると約104MB

まず、1行だけの hello.ts を実行ファイルにしました。--compile を付け、--outfile で出力するファイルの名前を指定します(公式ドキュメントの、単一ファイルの実行ファイルの説明)。

ts
console.log("Hello world!");
text
$ bun build ./hello.ts --compile --outfile hello
 [211ms]  bundle  1 modules
[1114ms] compile  hello
$ ./hello
Hello world!

できた hello は、109,123,760バイト(約104.07MB)ありました。Bun 本体(bun コマンドのファイル)は107,308,936バイト(約102.34MB)なので、ほとんどが Bun の実行環境の大きさです。公式ドキュメントにも、取り込んだファイルやパッケージと一緒に、Bun の実行環境のコピーが入ると書かれています。

file と ldd で見ると、普通の Linux の実行ファイルで、使っているのは glibc の基本的なライブラリだけでした。

text
$ file hello
hello: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, for GNU/Linux 3.2.0, BuildID[sha1]=588d7307f333293c728b74df19b7323c20736899, not stripped
$ ldd hello
	linux-vdso.so.1 (0x00007fcdacb94000)
	libc.so.6 => /lib/x86_64-linux-gnu/libc.so.6 (0x00007fcdac800000)
	/lib64/ld-linux-x86-64.so.2 (0x00007fcdacb96000)
	libpthread.so.0 => /lib/x86_64-linux-gnu/libpthread.so.0 (0x00007fcdacb7c000)
	libdl.so.2 => /lib/x86_64-linux-gnu/libdl.so.2 (0x00007fcdacb77000)
	libm.so.6 => /lib/x86_64-linux-gnu/libm.so.6 (0x00007fcdaca8e000)

引数を受け取る CLI を、Bun のない場所で動かす

もう少し CLI らしい例として、名前を受け取ってあいさつを表示する cli.ts を作りました。メッセージは別の JSON ファイルから import し、バージョンはビルドのときに --define で埋め込みます。

ts
import { parseArgs } from "node:util";
import messages from "./messages.json";

declare const BUILD_VERSION: string;

const { values, positionals } = parseArgs({
  args: Bun.argv.slice(2),
  options: {
    lang: { type: "string", default: "ja" },
    version: { type: "boolean", default: false },
  },
  allowPositionals: true,
});

if (values.version) {
  console.log(`neko-hello ${typeof BUILD_VERSION === "string" ? BUILD_VERSION : "dev"}`);
  console.log(`bun ${Bun.version}`);
  console.log(`standalone: ${Bun.isStandaloneExecutable}`);
  process.exit(0);
}

const lang = values.lang as keyof typeof messages;
const name = positionals[0] ?? "ねこ";
console.log(messages[lang].replace("{name}", name));
json
{
  "ja": "こんにちは、{name}さん",
  "en": "Hello, {name}!"
}

値は "1.0.0" のようにダブルクォートを含めて渡すので、--define BUILD_VERSION='"1.0.0"' のように全体を ' で囲みます。公式ドキュメントの、ビルド時の定数の例も同じ書き方です。

text
$ bun build ./cli.ts --compile --define BUILD_VERSION='"1.0.0"' --outfile neko-hello
   [3ms]  bundle  2 modules
 [175ms] compile  neko-hello
$ ./neko-hello たま
こんにちは、たまさん
$ ./neko-hello --lang en たま
Hello, たま!
$ ./neko-hello --version
neko-hello 1.0.0
bun 1.4.4
standalone: true

messages.json は実行ファイルの中に取り込まれています。比べるために bun cli.ts --version で直接実行すると、neko-hello dev と standalone: false が出ました。--define の値はビルドのときに埋め込まれるので、bun cli.ts で直接実行したときには入りません。Bun.isStandaloneExecutable を見ると、実行ファイルとして動いているかどうかを見分けられます(公式ドキュメントにある、実行ファイルとして動いているかを調べる方法)。

次に、できた neko-hello だけを別のフォルダにコピーし、PATH から Bun を外した状態で実行しました。

text
$ env -i PATH=/usr/bin:/bin bash -c 'command -v bun || echo "bun: not found"; cd /path/to/elsewhere && ls && ./neko-hello みけ'
bun: not found
neko-hello
こんにちは、みけさん

コピー先のフォルダのパスは /path/to/elsewhere に置き換えています。フォルダには neko-hello しかなく、Bun もありませんが、そのまま動きました。

大きさは、取り込むコードの量で増える

あいさつの CLI を実行ファイルにしても、大きさは Hello world と同じ109,123,760バイトでした。--minify、--minify --sourcemap を付けても変わらず、--bytecode まで付けて 109,398,192バイト(約104.33MB)です。バンドルした JavaScript は765バイト(--minify で561バイト)しかなく、実行ファイルの大きさには差が出ませんでした。

そこで、大きなパッケージを使う例として、typescript パッケージ(5.9.3)で TypeScript のコードを JavaScript に変換する check.ts を作りました。typescript の本体の typescript.js は、9,112,572バイト(約8.69MB)あります。

ts
import ts from "typescript";

// 引数で受け取った TypeScript のコードを、JavaScript に変換して表示する
const code = Bun.argv[2] ?? "const n: number = 1;";
const { outputText } = ts.transpileModule(code, {
  compilerOptions: { target: ts.ScriptTarget.ES2022 },
});
console.log(`typescript ${ts.version}`);
console.log(outputText.trim());

これを、公式ドキュメントの本番で使うときのおすすめに出てくる --minify、--sourcemap、--bytecode の組み合わせで実行ファイルにし、大きさと、10回ずつ実行したときの時間を比べました。

付けたオプション 大きさ 実行時間(10回の中央値)
なし 117,917,872バイト(112.46MB) 214ミリ秒
--minify 112,744,624バイト(107.52MB) 175ミリ秒
--minify --sourcemap 116,680,880バイト(111.28MB) 174ミリ秒
--minify --sourcemap --bytecode 128,059,568バイト(122.13MB) 49ミリ秒
bun build --compile で作った実行ファイルの大きさの横棒グラフ。Bun 本体が 102.34 MB、Hello world が 104.07 MB、typescript を使う CLI はオプションなしで 112.46 MB、--minify で 107.52 MB、--minify --sourcemap で 111.28 MB、--minify --sourcemap --bytecode で 122.13 MB
Bun 本体と、Linux x64 向けに作った実行ファイルの大きさ

typescript を取り込むと、Hello world より約8.4MB大きくなりました。bun build で JavaScript のファイルとして出力したときの大きさは、--minify なしで8,797,506バイト、ありで3,623,571バイトです。--minify を付けると実行ファイルも約4.9MB小さくなり、typescript を使う CLI の4通りの中では、いちばん小さくなりました。

--sourcemap を付けると、--minify だけのときより約3.8MB大きくなりました。公式ドキュメントによると、エラーのスタックトレースを元のファイルの位置で表示するために、zstd で圧縮したソースマップを実行ファイルに埋め込みます。このとき、実行ファイルの横に約12.49MBの .map ファイルもできましたが、実行ファイルだけを別のフォルダにコピーしても動きました。

--bytecode を付けると、さらに約10.9MB増えて122.13MBになりました。そのかわり、実行時間は175ミリ秒前後から49ミリ秒に縮んでいます。公式ドキュメントでは、JavaScript をバイトコードにする処理を、実行時からビルド時に移すオプションと説明されています。大きさを取るか、実行の速さを取るかで選ぶことになります。

実行時間は date +%s%N で前後の時刻を取って測った、検証用VMでの値です。実行のたびに数ミリ秒から数十ミリ秒の幅がありました。

他の OS や CPU 向けにも作れる

--target を付けると、ビルドしているのとは別の OS や CPU 向けの実行ファイルを作れます(公式ドキュメントの、他のプラットフォーム向けのビルドの説明)。Linux x64 の検証環境で、Hello world を6種類の向け先で作りました。

text
$ bun build ./hello.ts --compile --target=bun-windows-x64 --outfile cross/bun-windows-x64
   [3ms]  bundle  1 modules
[1341ms] compile  cross/bun-windows-x64.exe bun-windows-x64-v1.4.4

Windows 向けでは、--outfile に .exe を付けなくても、bun-windows-x64.exe という名前になりました。公式ドキュメントにも、Windows 向けでは .exe が自動で付くと書かれています。

--target 大きさ file コマンドの表示(抜粋)
bun-linux-x64 104.07MB ELF 64-bit、x86-64
bun-linux-arm64 104.17MB ELF 64-bit、ARM aarch64
bun-linux-x64-musl 97.95MB ELF 64-bit、x86-64、/lib/ld-musl-x86_64.so.1
bun-windows-x64 109.93MB PE32+ executable(console)x86-64
bun-darwin-arm64 85.03MB Mach-O 64-bit arm64
bun-darwin-x64 93.62MB Mach-O 64-bit x86_64

同じ Hello world でも、向け先によって85MBから110MBまで差がありました。いちばん小さいのは macOS の arm64 向け、いちばん大きいのは Windows 向けです。bun-linux-x64-musl は、glibc ではなく musl を C ライブラリに使う Linux 向けで、file の表示でも musl のローダーを使うことが分かります。

検証環境と同じ bun-linux-x64 以外は、ビルドの出力に bun-linux-aarch64-v1.4.4 のような名前が出ました。

配布するときは圧縮すると半分以下になる

約104MBのファイルをそのまま配るのは大きいので、Hello world の実行ファイルを圧縮して大きさを比べました。

形式 大きさ
圧縮なし 109,123,760バイト(104.07MB)
gzip(gzip -9) 51,627,840バイト(49.24MB)
zip(zip -9) 51,627,976バイト(49.24MB)
xz(xz -9) 38,080,668バイト(36.32MB)

gzip や zip で半分以下、xz では約35%になりました。

strip をかけると、中のプログラムが消える

Hello world の実行ファイルに strip をかけたところ、大きさは約50KB減っただけで、実行すると Hello world! ではなく、Bun 自体のヘルプが表示されました。

text
$ strip hello-stripped
$ ./hello-stripped
Bun is a fast JavaScript runtime, package manager, bundler, and test runner. (1.4.4+38afee6c8)

Usage: bun <command> [...flags] [...args]
(以下、bun コマンドのヘルプが続く)
注意

bun build --compile で作った実行ファイルに strip をかけないでください。検証環境では、strip は終了コード0で終わり、エラーは何も出ませんでした。

大きさを抑えたいときは、ここまでの結果のとおり、--minify を付けて取り込むコードを減らし、配布するときに圧縮するのが確実です。

​Posted by 86