يمكن أن يستغرق تكوين بيئة تطوير لـ Bun من 10 إلى 30 دقيقة اعتمادًا على اتصالك بالإنترنت وسرعة جهازك. ستحتاج إلى ~10 جيجابايت من المساحة الحرة في القرص للمستودع ومكونات البناء.

إذا كنت تستخدم Windows، يرجى الرجوع إلى هذا الدليل

استخدام Nix (بديل)

يتم توفير Nix flake كبديل لتثبيت التبعيات يدويًا:

nix develop
# أو استخدام الغلاف الصريح
# nix develop .#pure
export CMAKE_SYSTEM_PROCESSOR=$(uname -m)
bun bd

يوفر هذا جميع التبعيات في بيئة معزولة وقابلة للتكرار دون الحاجة إلى sudo.

تثبيت التبعيات (يدوي)

باستخدام مدير الحزم الخاص بنظامك، قم بتثبيت تبعيات Bun:

$ brew install automake cmake coreutils gnu-sed go icu4c libiconv libtool ninja pkg-config rust ruby sccache

$ sudo apt install curl wget lsb-release software-properties-common cargo cmake git golang libtool ninja-build pkg-config rustc ruby-full xz-utils

$ sudo pacman -S base-devel cmake git go libiconv libtool make ninja pkg-config python rust sed unzip ruby

$ sudo dnf install cargo clang19 llvm19 lld19 cmake git golang libtool ninja-build pkg-config rustc ruby libatomic-static libstdc++-static sed unzip which libicu-devel 'perl(Math::BigInt)'

$ sudo zypper install go cmake ninja automake git icu rustup && rustup toolchain install stable

ملاحظة: يتم تثبيت وتحديث مترجم Zig تلقائيًا بواسطة برامج نصية للبناء. لا يلزم التثبيت اليدوي.

قبل البدء، ستحتاج إلى تثبيت إصدار Bun بالفعل، حيث نستخدم أداة الحزم الخاصة بنا لترجمة وتصغير الكود، بالإضافة إلى برامج نصية لتوليد الكود.

$ curl -fsSL https://bun.com/install | bash

$ npm install -g bun

$ brew tap oven-sh/bun
$ brew install bun

اختياري: تثبيت sccache

يُستخدم sccache لتخزين مكونات الترجمة المؤقتة، مما يسرع البناء بشكل كبير. يجب تثبيته مع دعم S3:

# لـ macOS
$ brew install sccache

# لـ Linux. لاحظ أن الإصدار في مدير الحزم الخاص بك قد لا يحتوي على دعم S3.
$ cargo install sccache --features=s3

سيقوم هذا بتثبيت sccache مع دعم S3. ستكتشف برامجنا النصية للبناء وتستخدم sccache تلقائيًا مع ذاكرة التخزين المؤقت S3 المشتركة الخاصة بنا. ملاحظة: ليست جميع إصدارات sccache مترجمة مع دعم S3، لذا نوصي بتثبيته عبر cargo.

تسجيل بيانات اعتماد AWS لـ sccache (للمطورين الأساسيين فقط)

يمتلك المطورون الأساسيون وصول كتابة إلى ذاكرة التخزين المؤقت S3 المشتركة. لتمكين وصول الكتابة، يجب تسجيل الدخول باستخدام بيانات اعتماد AWS. أسهل طريقة للقيام بذلك هي استخدام aws CLI واستدعاء aws configure لتوفير معلومات أمان AWS الخاصة بك.

يجب أن تكتشف البرامج النصية cmake بيانات اعتماد AWS الخاصة بك تلقائيًا من البيئة أو ملف ~/.aws/credentials.

تسجيل الدخول إلى `aws` CLI

1. قم بتثبيت AWS CLI باتباع [الدليل الرسمي](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html).
2. قم بتسجيل الدخول إلى وحدة تحكم حساب AWS الخاص بك. سيقوم أحد أعضاء الفريق بتزويدك ببيانات الاعتماد الخاصة بك.
3. انقر على اسمك في الزاوية العلوية اليمنى > بيانات الأمان.
4. انتقل إلى "Access keys" وأنشئ مفتاح وصول جديد.
5. قم بتشغيل `aws configure` في طرفيتك وقدم معرف مفتاح الوصول ومفتاح الوصول السري عند المطالبة بهما.

المشاكل الشائعة التي قد تواجهها

- للتأكد من استخدام ذاكرة التخزين المؤقت، يمكنك استخدام أمر `sccache --show-stats` مباشرة بعد البناء. سيكشف هذا عن إحصائيات مفيدة جدًا، بما في ذلك الإصابات/الإخفاقات في ذاكرة التخزين المؤقت.
- إذا كان لديك ملفات تعريف AWS متعددة مكونة، فتأكد من تعيين ملف التعريف الصحيح في متغير البيئة `AWS_PROFILE`.
- يتبع `sccache` نموذج خادم-عميل. إذا واجهت مشاكل غريبة حيث يرفض `sccache` استخدام S3، على الرغم من أن لديك بيانات اعتماد AWS مكونة، فحاول قتل أي خوادم `sccache` قيد التشغيل باستخدام `sccache --stop-server` ثم إعادة تشغيل البناء.

تثبيت LLVM

يتطلب Bun LLVM 19 (clang هو جزء من LLVM). هذا الشرط للإصدار لمطابقة WebKit (المترجم مسبقًا)، حيث أن الإصدارات غير المتطابقة ستسبب فشل تخصيص الذاكرة في وقت التشغيل. في معظم الحالات، يمكنك تثبيت LLVM من خلال مدير حزم النظام الخاص بك:

$ brew install llvm@19

$ # يحتوي LLVM على برنامج تثبيت تلقائي متوافق مع جميع إصدارات Ubuntu
$ wget https://apt.llvm.org/llvm.sh -O - | sudo bash -s -- 19 all

$ sudo pacman -S llvm clang lld

$ sudo dnf install llvm clang lld-devel

$ sudo zypper install clang19 lld19 llvm19

إذا لم تنطبق أي من الحلول أعلاه، فسيتعين عليك تثبيته يدويًا.

تأكد من أن Clang/LLVM 19 في مسارك:

$ which clang-19

إذا لم يكن كذلك، قم بتشغيل هذا لإضافته يدويًا:

# استخدم fish_add_path إذا كنت تستخدم fish
# استخدم path+="$(brew --prefix llvm@19)/bin" إذا كنت تستخدم zsh
$ export PATH="$(brew --prefix llvm@19)/bin:$PATH"

# استخدم fish_add_path إذا كنت تستخدم fish
$ export PATH="$PATH:/usr/lib/llvm19/bin"

بناء Bun

بعد استنساخ المستودع، قم بتشغيل الأمر التالي للبناء. قد يستغرق هذا بعض الوقت حيث سيقوم باستنساخ الوحدات الفرعية وبناء التبعيات.

bun run build

سيتم وضع الملف الثنائي في ./build/debug/bun-debug. يُوصى بإضافة هذا إلى $PATH الخاص بك. للتحقق من نجاح البناء، دعنا نطبع رقم الإصدار على إصدار التطوير من Bun.

$ build/debug/bun-debug --version
x.y.z_debug

VSCode

VSCode هو IDE الموصى به للعمل على Bun، حيث تم تكوينه. بمجرد الفتح، يمكنك تشغيل Extensions: Show Recommended Extensions لتثبيت الإضافات الموصى بها لـ Zig و C++. يتم تكوين ZLS تلقائيًا.

إذا كنت تستخدم محررًا مختلفًا، فتأكد من إخبار ZLS باستخدام مترجم Zig المثبت تلقائيًا، الموجود في ./vendor/zig/zig.exe. اسم الملف هو zig.exe حتى يعمل كما هو متوقع على Windows، لكنه لا يزال يعمل على macOS/Linux (لديه فقط امتداد ملف مفاجئ).

نوصي بإضافة ./build/debug إلى $PATH الخاص بك حتى تتمكن من تشغيل bun-debug في طرفيتك:

bun-debug

تشغيل إصدارات التصحيح

يقوم البرنامج النصي bd في package.json بتجميع وتشغيل إصدار تصحيح من Bun، مع طباعة إخراج عملية البناء فقط إذا فشل.

bun bd <args>
bun bd test foo.test.ts
bun bd ./foo.ts

يستغرق Bun حوالي 2.5 دقيقة لتجميع إصدار تصحيح عند وجود تغييرات في Zig. إذا كانت سير عمل التطوير الخاص بك هو "تغيير سطر واحد، حفظ، إعادة بناء"، فستقضي الكثير من الوقت في انتظار انتهاء البناء. بدلاً من ذلك:

• قم بتجميع تغييراتك
• تأكد من تشغيل zls مع المراقبة التدريجية لأخطاء LSP (إذا كنت تستخدم VSCode وقمت بتثبيت Zig وتشغيل bun run build مرة واحدة لتنزيل Zig، يجب أن يعمل هذا بشكل صحيح)
• يفضل استخدام مصحح الأخطاء ("CodeLLDB" في VSCode) للتنقل خلال الكود.
• استخدم سجلات التصحيح. BUN_DEBUG_<scope>=1 سيمكن تسجيل التصحيح لنطاق Output.scoped(.<scope>, .hidden) المقابل. يمكنك أيضًا تعيين BUN_DEBUG_QUIET_LOGS=1 لتعطيل جميع سجلات التصحيح التي لم يتم تمكينها صراحةً. لتفريغ سجلات التصحيح في ملف، BUN_DEBUG=<path-to-file>.log. تتم إزالة سجلات التصحيح بشكل عدواني في إصدارات الإصدار.
• تغييرات src/js/**.ts فورية تقريبًا لإعادة البناء. تغييرات C++ أبطأ قليلاً، لكنها لا تزال أسرع بكثير من كود Zig (Zig هي وحدة تجميع واحدة، C++ هي العديد).

برامج نصية لتوليد الكود

يتم استخدام العديد من البرامج النصية لتوليد الكود أثناء عملية بناء Bun. يتم تشغيل هذه تلقائيًا عند إجراء تغييرات على ملفات معينة.

على وجه الخصوص، هذه هي:

• ./src/codegen/generate-jssink.ts -- ينشئ build/debug/codegen/JSSink.cpp، build/debug/codegen/JSSink.h التي تطبق فئات مختلفة للواجهة مع ReadableStream. هذه هي الطريقة التي تعمل بها داخليًا FileSink، ArrayBufferSink، تيارات "type": "direct" والكود الأخر المتعلق بالتيارات.
• ./src/codegen/generate-classes.ts -- ينشئ build/debug/codegen/ZigGeneratedClasses*، الذي ينشئ روابط Zig و C++ لفئات JavaScriptCore المطبقة في Zig. في ملفات **/*.classes.ts، نحدد واجهات الفئات المختلفة، الطرق، النماذج الأولية، getters/setters وما إلى ذلك التي يقرأها مولد الكود لتوليد الكود الأساسي الذي يطبق كائنات JavaScript في C++ وربطها بـ Zig
• ./src/codegen/cppbind.ts -- ينشئ روابط Zig تلقائية لدوال C++ المحددة بسمات [[ZIG_EXPORT]].
• ./src/codegen/bundle-modules.ts -- يجمع الوحدات المدمجة مثل node:fs، bun:ffi في ملفات يمكننا تضمينها في الملف الثنائي النهائي. في التطوير، يمكن إعادة تحميل هذه دون إعادة بناء Zig (لا يزال يتعين عليك تشغيل bun run build، لكنه يعيد قراءة الملفات المترجمة من القرص بعد ذلك). في إصدارات الإصدار، يتم تضمين هذه في الملف الثنائي.
• ./src/codegen/bundle-functions.ts -- يجمع الدوال التي يمكن الوصول إليها عالميًا والمطبقة في JavaScript/TypeScript مثل ReadableStream، WritableStream، وعدد قليل آخر. يتم استخدام هذه بشكل مشابه للوحدات المدمجة، لكن الإخراج يتوافق بشكل أكبر مع ما يفعله WebKit/Safari لدوال Safari المدمجة حتى نتمكن من نسخ ولصق التطبيقات من WebKit كنقطة انطلاق.

تعديل وحدات ESM

يتم تنفيذ وحدات معينة مثل node:fs، node:stream، bun:sqlite، و ws في JavaScript. تعيش هذه في ملفات src/js/{node,bun,thirdparty} ويتم تجميعها مسبقًا باستخدام Bun.

إصدار الإصدار

لتجميع إصدار إصدار من Bun، قم بتشغيل:

bun run build:release

سيتم وضع الملف الثنائي في ./build/release/bun و ./build/release/bun-profile.

تنزيل إصدار الإصدار من طلبات السحب

لتوفير الوقت الذي تقضيه في بناء إصدار إصدار محليًا، نوفر طريقة لتشغيل إصدارات الإصدار من طلبات السحب. هذا مفيد للاختبار اليدوي للتغييرات في إصدار إصدار قبل دمجها.

لتشغيل إصدار إصدار من طلب سحب، يمكنك استخدام حزمة npm bun-pr:

bunx bun-pr <pr-number>
bunx bun-pr <branch-name>
bunx bun-pr "https://github.com/oven-sh/bun/pull/1234566"
bunx bun-pr --asan <pr-number> # Linux x64 فقط

سيقوم هذا بتنزيل إصدار الإصدار من طلب السحب وإضافته إلى $PATH باسم bun-${pr-number}. يمكنك بعد ذلك تشغيل البناء باستخدام bun-${pr-number}.

bun-1234566 --version

يعمل هذا عن طريق تنزيل إصدار الإصدار من GitHub Actions artifacts على طلب السحب المرتبط. قد تحتاج إلى تثبيت gh CLI للمصادقة مع GitHub.

AddressSanitizer

يساعد AddressSanitizer في العثور على مشاكل الذاكرة، وهو مُمكّن افتراضيًا في إصدارات التصحيح من Bun على Linux و macOS. يتضمن هذا كود Zig وجميع التبعيات. يجعل كود Zig يستغرق حوالي ضعف الوقت للبناء، إذا كان ذلك يمنعك من أن تكون منتجًا يمكنك تعطيله عن طريق تعيين -Denable_asan=$<IF:$<BOOL:${ENABLE_ASAN}>,true,false> إلى -Denable_asan=false في ملف cmake/targets/BuildBun.cmake، لكننا نوصي عمومًا بتجميع تغييراتك بين البناء.

لبناء إصدار إصدار مع Address Sanitizer، قم بتشغيل:

bun run build:release:asan

في CI، نشغل مجموعة الاختبارات الخاصة بنا مع هدف واحد على الأقل يتم بناؤه باستخدام Address Sanitizer.

بناء WebKit محليًا + وضع التصحيح لـ JSC

لا يتم استنساخ WebKit افتراضيًا (لتوفير الوقت ومساحة القرص). لاستنساخ وبناء WebKit محليًا، قم بتشغيل:

# استنساخ WebKit في ./vendor/WebKit
$ git clone https://github.com/oven-sh/WebKit vendor/WebKit

# التحقق من تجزئة الالتزام المحددة في `set(WEBKIT_VERSION <commit_hash>)` في cmake/tools/SetupWebKit.cmake
$ git -C vendor/WebKit checkout <commit_hash>

# إنشاء بناء تصحيح لـ JSC. سيخرج مكونات البناء في ./vendor/WebKit/WebKitBuild/Debug
# اختياريًا، يمكنك استخدام `bun run jsc:build` للبناء الإصدار
bun run jsc:build:debug && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# بعد تشغيل أولي لـ `make jsc-debug`، يمكنك إعادة بناء JSC باستخدام:
$ cmake --build vendor/WebKit/WebKitBuild/Debug --target jsc && rm vendor/WebKit/WebKitBuild/Debug/JavaScriptCore/DerivedSources/inspector/InspectorProtocolObjects.h

# بناء bun مع بناء JSC المحلي
bun run build:local

سيؤدي استخدام bun run build:local إلى بناء Bun في دليل ./build/debug-local (بدلاً من ./build/debug)، سيتعين عليك تغيير بضع أماكن لاستخدام هذا الدليل الجديد:

• السطر الأول في src/js/builtins.d.ts
• سطر CompilationDatabase في تكوين .clangd يجب أن يكون CompilationDatabase: build/debug-local
• في build.zig، يجب أن يكون خيار codegen_path هو build/debug-local/codegen (بدلاً من build/debug/codegen)
• في .vscode/launch.json، تستخدم العديد من التكوينات ./build/debug/، قم بتغييرها حسب الحاجة

لاحظ أن مجلد WebKit، بما في ذلك مكونات البناء، حجمه 8 جيجابايت+.

إذا كنت تستخدم بناء تصحيح JSC وتستخدم VScode، فتأكد من تشغيل أمر C/C++: Select a Configuration لتكوين intellisense للعثور على رؤوس التصحيح.

لاحظ أنه إذا قمت بإجراء تغييرات على شوكة WebKit الخاصة بنا، فسيتعين عليك أيضًا تغيير SetupWebKit.cmake للإشارة إلى تجزئة الالتزام.

استكشاف الأخطاء وإصلاحها

ملف 'span' غير موجود على Ubuntu

يستخدم مترجم Clang عادةً مكتبة C++ القياسية libstdc++ افتراضيًا. libstdc++ هي مكتبة C++ القياسية الافتراضية المقدمة من مجموعة مترجم GNU (GCC). بينما قد يرتبط Clang بمكتبة libc++، يتطلب هذا توفير العلم -stdlib صراحةً عند تشغيل Clang.

يعتمد Bun على ميزات C++20 مثل std::span، غير متوفرة في إصدارات GCC الأقل من 11. لا يحتوي GCC 10 على جميع ميزات C++20 المطبقة. نتيجة لذلك، قد يفشل تشغيل make setup مع الخطأ التالي:

fatal error: 'span' file not found
#include <span>
         ^~~~~~

قد تظهر المشكلة عند تشغيل bun setup في البداية على أن Clang غير قادر على تجميع برنامج بسيط:

The C++ compiler

  "/usr/bin/clang++-19"

is not able to compile a simple test program.

لإصلاح الخطأ، نحتاج إلى تحديث إصدار GCC إلى 11. للقيام بذلك، سنحتاج إلى التحقق مما إذا كان أحدث إصدار متاحًا في المستودعات الرسمية للتوزيع أو استخدام مستودع تابع لجهة خارجية يوفر حزم GCC 11. إليك الخطوات العامة:

$ sudo apt update
$ sudo apt install gcc-11 g++-11
# إذا فشل الأمر أعلاه مع `Unable to locate package gcc-11` نحتاج
# إلى إضافة مستودع APT
$ sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
# الآن قم بتشغيل `apt install` مرة أخرى
$ sudo apt install gcc-11 g++-11

الآن، نحتاج إلى تعيين GCC 11 كمترجم افتراضي:

$ sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-11 100
$ sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-11 100

libarchive

إذا رأيت خطأ على macOS عند تجميع libarchive، قم بتشغيل:

$ brew install pkg-config

macOS library not found for -lSystem

إذا رأيت هذا الخطأ عند التجميع، قم بتشغيل:

$ xcode-select --install

لا يمكن العثور على libatomic.a

يفترض Bun ربط libatomic ثابتًا، حيث لا تحتوي جميع الأنظمة عليه. إذا كنت تبني على توزيعة لا تحتوي على libatomic ثابت متاح، يمكنك تشغيل الأمر التالي لتمكين الربط الديناميكي:

bun run build -DUSE_STATIC_LIBATOMIC=OFF

قد لا يعمل إصدار Bun الذي تم بناؤه بهذه الطريقة على أنظمة أخرى.

استخدام bun-debug

• تعطيل التسجيل: BUN_DEBUG_QUIET_LOGS=1 bun-debug ... (لتعطيل جميع سجلات التصحيح)
• تمكين التسجيل لنطاق zig معين: BUN_DEBUG_EventLoop=1 bun-debug ... (للسماح بـ std.log.scoped(.EventLoop))
• يقوم Bun بترجمة كل ملف يشغله، لرؤية المصدر المنفذ الفعلي في إصدار التصحيح ابحث عنه في /tmp/bun-debug-src/...path/to/file، على سبيل المثال سيكون الإصدار المترجم لـ /home/bun/index.ts في /tmp/bun-debug-src/home/bun/index.ts