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

परिचय

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

तर्क

विशेषताएं
नाम	नाम; ज़रूरी है इस टारगेट के लिए यूनीक नाम. इससे सैंडबॉक्स की गई C/C++ लाइब्रेरी की पहचान होगी. नाम-सैपी आउटपुट टारगेट देखें.
deps	लेबल की सूची; यह विकल्प देना ज़रूरी नहीं है सैंडबॉक्स की गई C/C++ लाइब्रेरी में लिंक की जाने वाली अन्य लाइब्रेरी की सूची.
srcs	लेबल की सूची; यह विकल्प देना ज़रूरी नहीं है सैंडबॉक्स की गई C/C++ लाइब्रेरी बनाने के लिए, प्रोसेस की गई C और C++ फ़ाइलों की सूची. ये C/C++ सोर्स और हेडर फ़ाइलें हैं. ये जनरेट की गई हैं या नहीं. ज़्यादा जानकारी के लिए, cc_library दस्तावेज़ में srcs एट्रिब्यूट के बारे में दी गई जानकारी देखें.
hdrs	लेबल की सूची; यह विकल्प देना ज़रूरी नहीं है हेडर फ़ाइलों की सूची, जिन्हें सैंडबॉक्स की गई C/C++ लाइब्रेरी बनाने के लिए प्रोसेस किया जाता है. सैंडबॉक्स की परिभाषा (sandbox.h) यहां दी जानी चाहिए. अगर एम्बेड की गई SAPI लाइब्रेरी का इस्तेमाल किया जाता है और डिफ़ॉल्ट सैंडबॉक्स नीति काफ़ी है, तो इसे खाली छोड़ दें.
एम्बेड	बूलियन; ज़रूरी नहीं; डिफ़ॉल्ट रूप से True पर सेट होता है अगर यह वैल्यू True पर सेट है, तो सैंडबॉक्स की गई लाइब्रेरी को होस्ट कोड में एम्बेड किया जाना चाहिए. इससे 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	बूलियन; ज़रूरी नहीं; डिफ़ॉल्ट रूप से True पर सेट होता है DEPRECATED
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",
)