बिल्ड रूल गाइड

शुरुआती जानकारी

Sandboxed API (SAPI) को Google के Bazel बिल्ड सिस्टम या लोकप्रिय CMake मेटा बिल्ड सिस्टम के साथ इस्तेमाल किया जा सकता है. इस पेज पर Bazel के बारे में जानकारी दी गई है. हालांकि, CMake के लिए भी यही सुविधाएं उपलब्ध हैं. Bazel एक सुझाया गया बिल्ड सिस्टम है और इसके साथ इंटिग्रेट करना सबसे आसान है.

आपकी BUILD.bazel फ़ाइल में अपना होस्ट कोड बनाने के लिए एक बिल्ड नियम होगा. होस्ट कोड किसी लाइब्रेरी के सैंडबॉक्स किए गए वर्शन का इस्तेमाल कर सके, इसके लिए आपको एक बिल्ड टारगेट तैयार करना होगा. आपका होस्ट कोड इसका इस्तेमाल करेगा.

SAPI बिल्ड नियम

• sapi_library

sapi_library

sapi_library(name, deps, srcs, hdrs, embed, functions, lib, lib_name, input_files, namespace, header, add_default_deps, limit_scan_depth, visibility)

आउटपुट टारगेट

sapi_library() बिल्ड नियम, ये टारगेट जनरेट करता है:

• name-sapi: सैंडबॉक्स की गई लाइब्रेरी, इसकी जगह सामान्य cc_library को होस्ट कोड टारगेट के तौर पर इस्तेमाल करती है. इसमें zlib_sapi.bin और सैंडबॉक्स डिपेंडेंसी शामिल हैं.
• name.interface: लाइब्रेरी का जनरेट किया गया इंटरफ़ेस.
• name.embed: cc_embed_data() टारगेट का इस्तेमाल, Sandboxee को बाइनरी में जोड़ने के लिए किया जाता है. bazel/embed_data.bzl देखें.
• name.bin: Sandboxee बाइनरी में, एक छोटा कम्यूनिकेशन स्टब और एक लाइब्रेरी होती है, जिसे सैंडबॉक्स किया जा रहा है.

तर्क

एट्रिब्यूट
नाम	नाम; ज़रूरी है इस टारगेट के लिए एक खास नाम. इससे सैंडबॉक्स की गई C/C++ लाइब्रेरी की पहचान होगी, name-sapi आउटपुट टारगेट देखें.
डिग्री	लेबल की सूची; ज़रूरी नहीं सैंडबॉक्स की गई C/C++ लाइब्रेरी से लिंक की जाने वाली दूसरी लाइब्रेरी की सूची.
srcs	लेबल की सूची; ज़रूरी नहीं C और C++ फ़ाइलों की ऐसी सूची जिन्हें सैंडबॉक्स की गई C/C++ लाइब्रेरी बनाने के लिए प्रोसेस किया जाता है. ये C/C++ सोर्स और हेडर फ़ाइलें होती हैं. ये फ़ाइलें या तो जनरेट नहीं होती हैं (सामान्य सोर्स कोड) या जनरेट होती हैं. ज़्यादा जानकारी के लिए, cc_library दस्तावेज़ में एट्रिब्यूट srcs के बारे में दी गई जानकारी देखें.
एचडीआर	लेबल की सूची; ज़रूरी नहीं हेडर फ़ाइलों की सूची, जिन्हें सैंडबॉक्स की गई C/C++ लाइब्रेरी बनाने के लिए प्रोसेस किया जाता है. यहां सैंडबॉक्स डेफ़िनिशन (सैंडबॉक्स.h) का इस्तेमाल किया जाना चाहिए. अगर एम्बेड की गई SAPI लाइब्रेरी का इस्तेमाल किया जाता है, तो इसे खाली छोड़ दें और डिफ़ॉल्ट सैंडबॉक्स नीति काफ़ी हो.
एम्बेड	बूलियन; वैकल्पिक; डिफ़ॉल्ट 'सही है' पर सेट है अगर 'सही है' पर सेट है, तो सैंडबॉक्स की गई लाइब्रेरी को होस्ट कोड के अंदर एम्बेड किया जाना चाहिए. इससे, SAPI सैंडबॉक्स को ::sapi::Sandbox::Sandbox(FileToc*) कंस्ट्रक्टर के साथ शुरू किया जा सकता है.
फ़ंक्शन	फ़ंक्शन के नामों की सूची; ज़रूरी नहीं C/C++ लाइब्रेरी में मौजूद फ़ंक्शन की सूची, जिसके लिए सैंडबॉक्स वर्शन जनरेट किया जाता है. इसके बाद, उसे होस्ट कोड में इस्तेमाल किया जा सकता है. एक खाली सूची में, लाइब्रेरी में मौजूद सभी फ़ंक्शन को एक्सपोर्ट और रैप करने की कोशिश की जाएगी.
lib	स्ट्रिंग; ज़रूरी है C/C++ लाइब्रेरी टारगेट का नाम जो सैंडबॉक्स की गई लाइब्रेरी होगा. इसका मतलब है कि आपके पास प्रोजेक्ट में C/C++ लाइब्रेरी के लिए, cc_library बनाने का नियम होना चाहिए.
lib_name	स्ट्रिंग; ज़रूरी है SAPI ऑब्जेक्ट का नाम, जिसका इस्तेमाल फ़ंक्शन एट्रिब्यूट से लाइब्रेरी फ़ंक्शन को प्रॉक्सी करने के लिए किया जाता है. सैंडबॉक्स की गई लाइब्रेरी में फ़ंक्शन को कोई भी कॉल, SAPI ऑब्जेक्ट के ज़रिए किया जाएगा.
input_files	लेबल की सूची; ज़रूरी नहीं C और C++ फ़ाइलों की सूची, जो sapi_interface नियम के इंटरनल रन के दौरान प्रोसेस होती हैं. जनरेटर, C/C++ लाइब्रेरी के फ़ंक्शन से जुड़े एलान के लिए इन फ़ाइलों को स्कैन करता है. इसकी ज़्यादातर ज़रूरत नहीं है, क्योंकि C/C++ लाइब्रेरी के एक्सपोर्ट किए गए हेडर हमेशा स्कैन किए जाते हैं.
नाम स्थान	स्ट्रिंग; ज़रूरी नहीं; डिफ़ॉल्ट तौर पर sapigen होता है C++ नेमस्पेस आइडेंटिफ़ायर, जिसमें lib_name से तय किए गए SAPI ऑब्जेक्ट को शामिल किया जाता है. डिफ़ॉल्ट नेमस्पेस sapigen है.
हेडर	स्ट्रिंग; ज़रूरी नहीं इस्तेमाल करने के लिए, जनरेट की गई हेडर फ़ाइल का नाम. इसके बजाय, हेडर फ़ाइल का नाम. अगर आपको कोड अपने-आप जनरेट करना है, तो इस एट्रिब्यूट का इस्तेमाल न करें
add_default_deps	बूलियन; वैकल्पिक; डिफ़ॉल्ट 'सही है' पर सेट है रोक दी गई है
limit_scan_depth	बूलियन; वैकल्पिक; डिफ़ॉल्ट रूप से गलत है कॉम्प्लेक्स लाइब्रेरी के लिए, हो सकता है कि Bazel की फ़ाइल की संख्या पूरी हो जाए. हालांकि, बिल्ड प्रोसेस पूरी नहीं हो पाएगी. यह एट्रिब्यूट, इन मुश्किल स्थितियों से बचने का एक तरीका है. जब तक ज़रूरी न हो, तब तक इस्तेमाल न करें.
टैग	टैग के लिए Bazel दस्तावेज़ देखें.
किसे दिखे	किसे दिखे के लिए, Bazel का दस्तावेज़ देखें

इस्तेमाल का उदाहरण

zlib का उदाहरण एक अच्छा रेफ़रंस प्रोजेक्ट है. इससे यह पता चलता है कि sapi_library बिल्ड नियम का इस्तेमाल कैसे किया जाता है:

load(
    "//sandboxed_api/tools/generator:sapi_generator.bzl",
    "sapi_library",
)

sapi_library(
    name = "zlib-sapi",
    srcs = [],     # Extra code compiled with the SAPI library
    hdrs = [],     # Leave empty if embedded SAPI libraries are used, and the
                   # default sandbox policy is sufficient.
    embed = True,  # This is the default
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@zlib//:zlibonly",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)