नेटिव्स बिल्ड, रिलीज़ और डिबगिंग रनबुक

यह रनबुक वर्णन करता है कि @f5-sales-demo/pi-natives बिल्ड पाइपलाइन .node एडऑन कैसे उत्पन्न करती है, संकलित वितरण उन्हें कैसे लोड करते हैं, और लोडर/बिल्ड विफलताओं को कैसे डिबग किया जाए।

यह docs/natives-architecture.md की आर्किटेक्चर शब्दावली का अनुसरण करता है:

• बिल्ड-टाइम आर्टिफ़ैक्ट उत्पादन (scripts/build-native.ts)
• एम्बेडेड एडऑन मैनिफेस्ट जनरेशन (scripts/embed-native.ts)
• रनटाइम एडऑन लोडिंग + वैलिडेशन गेट (src/native.ts)

कार्यान्वयन फ़ाइलें

• packages/natives/scripts/build-native.ts
• packages/natives/scripts/embed-native.ts
• packages/natives/package.json
• packages/natives/src/native.ts
• crates/pi-natives/Cargo.toml

बिल्ड पाइपलाइन अवलोकन

1) बिल्ड एंट्रीपॉइंट्स

packages/natives/package.json स्क्रिप्ट्स:

• bun scripts/build-native.ts (build) → रिलीज़ बिल्ड
• bun scripts/build-native.ts --dev (dev:native) → डिबग/डेव प्रोफ़ाइल बिल्ड (समान आउटपुट नामकरण)
• bun scripts/embed-native.ts (embed:native) → बिल्ट फ़ाइलों से src/embedded-addon.ts उत्पन्न करें

2) Rust आर्टिफ़ैक्ट बिल्ड

build-native.ts crates/pi-natives में Cargo चलाता है:

• बेस कमांड: cargo build
• रिलीज़ मोड में --dev पास न होने पर --release जुड़ता है
• क्रॉस टार्गेट --target <CROSS_TARGET> जोड़ता है

crates/pi-natives/Cargo.toml crate-type = ["cdylib"] घोषित करता है, इसलिए Cargo एक शेयर्ड लाइब्रेरी (.so/.dylib/.dll) उत्पन्न करता है जिसे फिर .node एडऑन फ़ाइलनाम में कॉपी/रीनेम किया जाता है।

3) आर्टिफ़ैक्ट खोज और इंस्टॉल

Cargo पूर्ण होने के बाद, build-native.ts क्रम में उम्मीदवार आउटपुट डायरेक्ट्री स्कैन करता है:

1. ${CARGO_TARGET_DIR} (यदि सेट हो)
2. <repo>/target
3. crates/pi-natives/target

प्रत्येक रूट के लिए यह प्रोफ़ाइल डायरेक्ट्री जाँचता है:

• क्रॉस बिल्ड: <root>/<crossTarget>/<profile> फिर <root>/<profile>
• नेटिव बिल्ड: <root>/<profile>

फिर यह निम्न में से एक ढूँढता है:

• libpi_natives.so
• libpi_natives.dylib
• pi_natives.dll
• libpi_natives.dll

मिलने पर, यह टेम्प-फ़ाइल + रीनेम सेमेंटिक्स के साथ packages/natives/native/ में अटॉमिकली इंस्टॉल करता है (Windows फ़ॉलबैक लॉक्ड DLL प्रतिस्थापन विफलताओं को स्पष्ट रूप से संभालता है)।

टार्गेट/वेरिएंट मॉडल और नामकरण परंपराएँ

प्लेटफ़ॉर्म टैग

बिल्ड और रनटाइम दोनों प्लेटफ़ॉर्म टैग उपयोग करते हैं:

<platform>-<arch> (उदाहरण: darwin-arm64, linux-x64)

वेरिएंट मॉडल (केवल x64)

x64 CPU वेरिएंट्स का समर्थन करता है:

• modern (AVX2-सक्षम पथ)
• baseline (फ़ॉलबैक)

गैर-x64 एकल डिफ़ॉल्ट आर्टिफ़ैक्ट उपयोग करता है (कोई वेरिएंट प्रत्यय नहीं)।

आउटपुट फ़ाइलनाम

रिलीज़ बिल्ड:

• x64: pi_natives.<platform>-<arch>-modern.node या ...-baseline.node
• गैर-x64: pi_natives.<platform>-<arch>.node

डेव बिल्ड (--dev):

• डिबग प्रोफ़ाइल फ़्लैग उपयोग करता है लेकिन मानक प्लेटफ़ॉर्म-टैग्ड आउटपुट नामकरण बनाए रखता है

native.ts में रनटाइम लोडर उम्मीदवार क्रम:

• रिलीज़ उम्मीदवार
• कंपाइल्ड मोड पैकेज-लोकल फ़ाइलों से पहले निकाले गए/कैश उम्मीदवार जोड़ता है

एनवायरनमेंट फ़्लैग और बिल्ड विकल्प

रनटाइम फ़्लैग

• PI_DEV (लोडर व्यवहार): लोडर डायग्नोस्टिक्स सक्षम करें
• PI_NATIVE_VARIANT (लोडर व्यवहार, केवल x64): रनटाइम पर modern या baseline चयन बाध्य करें
• PI_COMPILED (लोडर व्यवहार): कंपाइल्ड-बाइनरी उम्मीदवार/निष्कर्षण व्यवहार सक्षम करें

बिल्ड-टाइम फ़्लैग/विकल्प

• --dev (स्क्रिप्ट आर्ग): डिबग प्रोफ़ाइल बिल्ड
• CROSS_TARGET: Cargo --target को पास किया जाता है
• TARGET_PLATFORM: आउटपुट प्लेटफ़ॉर्म टैग नामकरण ओवरराइड करें
• TARGET_ARCH: आउटपुट आर्क नामकरण ओवरराइड करें
• TARGET_VARIANT (केवल x64): आउटपुट फ़ाइलनाम और RUSTFLAGS नीति के लिए modern या baseline बाध्य करें
• CARGO_TARGET_DIR: Cargo आउटपुट खोजते समय अतिरिक्त रूट
• RUSTFLAGS:
  • यदि अनसेट हो और क्रॉस-कंपाइलिंग न हो, स्क्रिप्ट सेट करती है:
    • modern: -C target-cpu=x86-64-v3
    • baseline: -C target-cpu=x86-64-v2
    • गैर-x64 / कोई वेरिएंट नहीं: -C target-cpu=native
  • यदि पहले से सेट हो, स्क्रिप्ट ओवरराइड नहीं करती

बिल्ड स्टेट/लाइफसाइकिल ट्रांज़िशन

बिल्ड लाइफसाइकिल (build-native.ts)

1. Init: आर्ग/env पार्स करें (--dev, टार्गेट ओवरराइड, क्रॉस फ़्लैग)
2. वेरिएंट रिज़ॉल्व:
   • गैर-x64 → कोई वेरिएंट नहीं
   • x64 + TARGET_VARIANT → स्पष्ट वेरिएंट
   • x64 क्रॉस-बिल्ड बिना TARGET_VARIANT → हार्ड एरर
   • x64 लोकल बिल्ड बिना ओवरराइड → होस्ट AVX2 डिटेक्ट करें
3. कंपाइल: रिज़ॉल्व्ड प्रोफ़ाइल/टार्गेट के साथ Cargo चलाएँ
4. आर्टिफ़ैक्ट लोकेट: टार्गेट रूट/प्रोफ़ाइल डायरेक्ट्री/लाइब्रेरी नाम स्कैन करें
5. इंस्टॉल: packages/natives/native में कॉपी + अटॉमिक रीनेम
6. पूर्ण: एडऑन लोडर उम्मीदवारों के लिए तैयार

किसी भी चरण में विफलता होने पर स्पष्ट एरर टेक्स्ट के साथ एग्ज़िट होता है (अमान्य वेरिएंट, विफल cargo बिल्ड, गायब आउटपुट लाइब्रेरी, इंस्टॉल/रीनेम विफलता)।

एम्बेड लाइफसाइकिल (embed-native.ts)

1. Init: TARGET_PLATFORM/TARGET_ARCH या होस्ट वैल्यू से प्लेटफ़ॉर्म टैग कंप्यूट करें
2. उम्मीदवार सेट:
   • x64 दोनों modern और baseline की अपेक्षा करता है
   • गैर-x64 एक डिफ़ॉल्ट फ़ाइल की अपेक्षा करता है
3. packages/natives/native में उपलब्धता वैलिडेट करें
4. Bun file इम्पोर्ट और पैकेज वर्शन के साथ मैनिफेस्ट जनरेट करें (src/embedded-addon.ts)
5. कंपाइल्ड मोड के लिए रनटाइम निष्कर्षण तैयार

--reset वैलिडेशन बायपास करता है और एक null मैनिफेस्ट स्टब (embeddedAddon = null) लिखता है।

डेव वर्कफ़्लो बनाम शिप्ड/कंपाइल्ड व्यवहार

लोकल डेवलपमेंट वर्कफ़्लो

सामान्य लोकल लूप:

1. एडऑन बिल्ड करें:
   • रिलीज़: bun --cwd=packages/natives run build
   • डिबग प्रोफ़ाइल: bun --cwd=packages/natives run dev:native
2. लोडर डायग्नोस्टिक्स परीक्षण करते समय PI_DEV=1 सेट करें
3. native.ts में लोडर पैकेज-लोकल native/ (और एग्ज़ीक्यूटेबल-डायर फ़ॉलबैक) उम्मीदवार रिज़ॉल्व करता है
4. validateNative रैपर बाइंडिंग उपयोग करने से पहले एक्सपोर्ट संगतता लागू करता है

शिप्ड/कंपाइल्ड बाइनरी वर्कफ़्लो

कंपाइल्ड मोड में (PI_COMPILED या Bun एम्बेडेड मार्कर):

1. लोडर वर्शन्ड कैश डायरेक्ट्री कंप्यूट करता है: <getNativesDir()>/<packageVersion> (परिचालन रूप से ~/.xcsh/natives/<version>)
2. यदि एम्बेडेड मैनिफेस्ट वर्तमान प्लेटफ़ॉर्म+वर्शन से मेल खाता है, लोडर उस वर्शन्ड डायरेक्ट्री में चयनित एम्बेडेड फ़ाइल निकाल सकता है
3. रनटाइम उम्मीदवार क्रम में शामिल हैं:
   • वर्शन्ड कैश डायरेक्ट्री
   • लेगेसी कंपाइल्ड-बाइनरी डायरेक्ट्री (Windows पर %LOCALAPPDATA%/xcsh, अन्यत्र ~/.local/bin)
   • पैकेज/एग्ज़ीक्यूटेबल डायरेक्ट्री
4. सफलतापूर्वक लोड हुए पहले एडऑन को भी validateNative पास करना होगा

इसीलिए पैकेजिंग + रनटाइम लोडर अपेक्षाएँ संरेखित होनी चाहिए: फ़ाइलनाम, प्लेटफ़ॉर्म टैग, और एक्सपोर्ट किए गए सिंबल को native.ts जाँचता और वैलिडेट करता है, उनसे मेल खाना चाहिए।

JS API ↔ Rust एक्सपोर्ट मैपिंग (वैलिडेशन गेट सबसेट)

native.ts के लिए लोड किए गए एडऑन पर ये JS-दृश्यमान एक्सपोर्ट मौजूद होना आवश्यक है। वे crates/pi-natives/src में Rust N-API एक्सपोर्ट से मैप होते हैं:

validateNative द्वारा आवश्यक JS नाम	Rust एक्सपोर्ट घोषणा	Rust सोर्स फ़ाइल
glob	#[napi] pub fn glob(...)	crates/pi-natives/src/glob.rs
grep	#[napi] pub fn grep(...)	crates/pi-natives/src/grep.rs
search	#[napi] pub fn search(...)	crates/pi-natives/src/grep.rs
highlightCode	#[napi] pub fn highlight_code(...)	crates/pi-natives/src/highlight.rs
getSystemInfo	#[napi] pub fn get_system_info(...)	crates/pi-natives/src/system_info.rs
getWorkProfile	#[napi] pub fn get_work_profile(...) (कैमल-केस्ड एक्सपोर्ट)	crates/pi-natives/src/prof.rs
invalidateFsScanCache	#[napi] pub fn invalidate_fs_scan_cache(...)	crates/pi-natives/src/fs_cache.rs

यदि कोई आवश्यक सिंबल गायब हो, तो लोडर रिबिल्ड संकेत के साथ तत्काल विफल हो जाता है।

विफलता व्यवहार और डायग्नोस्टिक्स

बिल्ड-टाइम विफलताएँ

• अमान्य वेरिएंट कॉन्फ़िगरेशन:
  • TARGET_VARIANT गैर-x64 पर सेट → तत्काल एरर
  • स्पष्ट TARGET_VARIANT के बिना x64 क्रॉस-बिल्ड → तत्काल एरर
• Cargo बिल्ड विफलता:
  • स्क्रिप्ट नॉन-ज़ीरो एग्ज़िट और stderr दिखाती है
• आर्टिफ़ैक्ट नहीं मिला:
  • स्क्रिप्ट हर जाँची गई प्रोफ़ाइल डायरेक्ट्री प्रिंट करती है
• इंस्टॉल विफलता:
  • स्पष्ट संदेश; Windows में लॉक्ड-फ़ाइल संकेत शामिल

रनटाइम लोडर विफलताएँ (native.ts)

• असमर्थित प्लेटफ़ॉर्म टैग:
  • समर्थित प्लेटफ़ॉर्म सूची के साथ थ्रो
• कोई उम्मीदवार लोड नहीं हो सका:
  • पूर्ण उम्मीदवार एरर सूची और मोड-विशिष्ट उपचार संकेतों के साथ थ्रो
• गायब एक्सपोर्ट:
  • सटीक गायब सिंबल नाम और रिबिल्ड कमांड के साथ थ्रो
• एम्बेडेड निष्कर्षण समस्याएँ:
  • निष्कर्षण mkdir/write एरर रिकॉर्ड किए जाते हैं और अंतिम डायग्नोस्टिक्स में शामिल होते हैं

समस्या निवारण मैट्रिक्स

लक्षण	संभावित कारण	जाँच करें	सुधार
Native addon missing exports ... Missing: <name>	पुरानी .node बाइनरी, Rust एक्सपोर्ट नाम मिसमैच, या गलत बाइनरी लोड हुई	लोड पथ देखने के लिए PI_DEV=1 के साथ चलाएँ; उस फ़ाइल की एक्सपोर्ट सूची जाँचें	build रिबिल्ड करें; सुनिश्चित करें कि Rust #[napi] एक्सपोर्ट नाम (या ज़रूरत होने पर स्पष्ट उपनाम) JS की से मेल खाता हो; पुरानी कैश/वर्शन्ड फ़ाइलें हटाएँ
x64 मशीन modern अपेक्षित होने पर baseline लोड करती है	PI_NATIVE_VARIANT=baseline, कोई AVX2 डिटेक्ट नहीं, या केवल baseline फ़ाइल मौजूद	PI_NATIVE_VARIANT जाँचें; -modern फ़ाइल के लिए native/ जाँचें	modern वेरिएंट बिल्ड करें (TARGET_VARIANT=modern ... build) और सुनिश्चित करें फ़ाइल शिप हो
क्रॉस-बिल्ड अनुपयोगी/गलत-लेबल्ड बाइनरी उत्पन्न करता है	CROSS_TARGET और TARGET_PLATFORM/TARGET_ARCH के बीच मिसमैच, या x64 के लिए TARGET_VARIANT गायब	env टपल और आउटपुट फ़ाइलनाम की पुष्टि करें	संगत env वैल्यू और स्पष्ट x64 TARGET_VARIANT के साथ पुनः चलाएँ
अपग्रेड के बाद कंपाइल्ड बाइनरी विफल	पुराना निकाला गया कैश (~/.xcsh/natives/<old-or-mismatched-version>) या एम्बेडेड मैनिफेस्ट मिसमैच	वर्शन्ड नेटिव्स डायरेक्ट्री और लोडर एरर सूची जाँचें	पैकेज वर्शन के लिए वर्शन्ड नेटिव्स कैश डिलीट करें और पुनः चलाएँ; पैकेजिंग के दौरान एम्बेडेड मैनिफेस्ट पुनः उत्पन्न करें
लोडर कई पथ जाँचता है और कोई काम नहीं करता	प्लेटफ़ॉर्म मिसमैच या पैकेज native/ में रिलीज़ आर्टिफ़ैक्ट गायब	वास्तविक फ़ाइलनाम(ों) के विरुद्ध platformTag जाँचें	सुनिश्चित करें कि बिल्ट फ़ाइलनाम ठीक pi_natives.<platform>-<arch>(-variant).node परंपरा से मेल खाए और पैकेज में native/ शामिल हो
embed:native “Incomplete native addons” के साथ विफल	एम्बेडिंग से पहले आवश्यक वेरिएंट फ़ाइलें नहीं बनीं	एरर टेक्स्ट में अपेक्षित बनाम मिली सूची जाँचें	पहले आवश्यक फ़ाइलें बिल्ड करें (x64: दोनों modern+baseline; गैर-x64: डिफ़ॉल्ट), फिर embed:native पुनः चलाएँ

परिचालन कमांड

# वर्तमान होस्ट के लिए रिलीज़ आर्टिफ़ैक्ट
bun --cwd=packages/natives run build

# डिबग प्रोफ़ाइल आर्टिफ़ैक्ट बिल्ड
bun --cwd=packages/natives run dev:native

# स्पष्ट x64 वेरिएंट बिल्ड करें
TARGET_VARIANT=modern bun --cwd=packages/natives run build
TARGET_VARIANT=baseline bun --cwd=packages/natives run build

# बिल्ट नेटिव फ़ाइलों से एम्बेडेड एडऑन मैनिफेस्ट जनरेट करें
bun --cwd=packages/natives run embed:native

# एम्बेडेड मैनिफेस्ट को null स्टब पर रीसेट करें
bun --cwd=packages/natives run embed:native -- --reset