Sandboxed API के साथ शुरू करना

इस पेज पर, आपको Sandboxed API (SAPI) की मदद से, सैंडबॉक्स की गई अपनी C/C++ लाइब्रेरी बनाने का तरीका बताया जाएगा. इसका इस्तेमाल, हेडर फ़ाइलों में दिए गए उदाहरणों और कोड के दस्तावेज़ों के साथ-साथ गाइड के तौर पर करें.

बिल्ड डिपेंडेंसी

सिस्टम पर ये डिपेंडेंसी इंस्टॉल होनी चाहिए:

  • Linux कर्नल, जिसमें यूटीएस, आईपीसी, उपयोगकर्ता, पीआईडी, और नेटवर्क नेमस्पेस के लिए सहायता उपलब्ध हो
  • Linux userspace API हेडर
  • कोड कंपाइल करने के लिए: GCC 6 (वर्शन 7 या इसके बाद का वर्शन इस्तेमाल करने का सुझाव दिया जाता है) या Clang 7 (या इसके बाद का वर्शन)
  • हेडर फ़ाइलें अपने-आप जनरेट करने के लिए: Clang Python Bindings
  • Python 3.5 या उसके बाद के वर्शन
  • Bazel का 2.2.0 वर्शन या CMake का 3.12 या इसके बाद का वर्शन.
    • सिर्फ़ CMake के लिए: GNU Make या libcap लाइब्रेरी हेडर का कोई वर्शन और Ninja (सुझाया गया) जैसे बिल्ड टूल.

Bazel का इस्तेमाल करना

Bazel को बिल्ड सिस्टम के तौर पर इस्तेमाल करने का सुझाव दिया जाता है. इसे इंटिग्रेट करना भी सबसे आसान है.

हमारे दस्तावेज़ में, Clang कंपाइलर का इस्तेमाल किया गया है. अगर आपको किसी खास टूलचेन (जैसे, कंपाइलर, लिंकर वगैरह) की ज़रूरत है, तो डिफ़ॉल्ट कंपाइलर टूलचेन को बदलने के तरीके के बारे में जानने के लिए, Bazel के दस्तावेज़ पढ़ें.

Debian 10 (Buster)

बिल्ड डिपेंडेंसी इंस्टॉल करने के लिए:

echo "deb http://storage.googleapis.com/bazel-apt stable jdk1.8" | \
  sudo tee /etc/apt/sources.list.d/bazel.list
wget -qO - https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
sudo apt-get update
sudo apt-get install -qy build-essential linux-libc-dev bazel python3 \
  python3-pip libclang-dev
pip3 install clang

Gentoo

कर्नेल के लिए ज़रूरी विकल्प:

General setup  --->
-*- Namespaces support
[*]   UTS namespace
[*]   IPC namespace
[*]   User namespace (EXPERIMENTAL)
[*]   PID Namespaces
[*]   Network namespace

बिल्ड डिपेंडेंसी इंस्टॉल करने के लिए:

emerge dev-util/bazel dev-python/typing dev-python/clang-python

CMake का इस्तेमाल करना

CMake एक लोकप्रिय ओपन-सोर्स मेटा बिल्ड सिस्टम है. यह Ninja या Make जैसे बिल्ड टूल के लिए प्रोजेक्ट फ़ाइलें जनरेट करता है.

Debian 10 (Buster)

बिल्ड डिपेंडेंसी इंस्टॉल करने के लिए:

sudo apt-get install -qy build-essential linux-libc-dev cmake ninja-build \
  python3 python3-pip libclang-dev libcap-dev
pip3 install absl-py clang

Gentoo

कर्नेल के लिए ज़रूरी विकल्प:

General setup  --->
-*- Namespaces support
[*]   UTS namespace
[*]   IPC namespace
[*]   User namespace (EXPERIMENTAL)
[*]   PID Namespaces
[*]   Network namespace

बिल्ड डिपेंडेंसी इंस्टॉल करने के लिए:

emerge sys-kernel/linux-headers dev-util/cmake dev-util/ninja \
dev-python/clang-python

डेवलपमेंट प्रोसेस

किसी C/C++ लाइब्रेरी को सैंडबॉक्स करने के लिए, आपको अपने प्रोजेक्ट के लिए दो आइटम तैयार करने होंगे:

आपको Sandbox2 के उदाहरणों से zlib के बारे में पता होगा. यहां एक पूरे प्रोग्राम (zpipe.c) को सैंडबॉक्स किया गया था. यहां दिए गए तरीके से, SAPI का इस्तेमाल करके zlib लाइब्रेरी को सैंडबॉक्स करने और सैंडबॉक्स की गई लाइब्रेरी का इस्तेमाल करने का तरीका जानें.

1. तय करें कि किन फ़ंक्शन की ज़रूरत है

zlib होस्ट कोड (main_zlib.cc) को देखने पर, आपको पता चलेगा कि टूल का काम stdin से डेटा पढ़ना है. साथ ही, EOF मार्कर पढ़े जाने तक, डेटा को कंप्रेस करने के लिए zlib के deflate() फ़ंक्शन का इस्तेमाल करना है. कुल मिलाकर, प्रोग्राम zlib के तीन फ़ंक्शन इस्तेमाल करता है:

  • deflateInit_(): कंप्रेस करने के लिए शुरू करना है
  • deflate(): इसका इस्तेमाल, डेटा के हिस्से पर कंप्रेस करने की कार्रवाई करने के लिए किया जाता है
  • deflateEnd(): कंप्रेस करने की प्रोसेस और डाइनैमिक तरीके से असाइन किए गए डेटा स्ट्रक्चर को बंद करने के लिए

असल ज़िंदगी के उदाहरण में, C/C++ लाइब्रेरी की समीक्षा की जाती है. इसके बाद, यह तय किया जाता है कि किन फ़ंक्शन की ज़रूरत है. हो सकता है कि आपको होस्ट कोड से शुरुआत करनी पड़े और लाइब्रेरी को अनसैंडबॉक्स मोड में इस्तेमाल करना पड़े. इसके बाद, दूसरे चरण में सैंडबॉक्स की गई लाइब्रेरी जनरेट की जा सकती है. साथ ही, सैंडबॉक्स किए गए फ़ंक्शन कॉल का इस्तेमाल करने के लिए, होस्ट कोड में बदलाव किया जा सकता है.

2. sapi_library के लिए Build Rule लिखना

सैंडबॉक्स की गई zlib लाइब्रेरी से ज़रूरी तीन zlib फ़ंक्शन की पहचान करने के बाद, BUILD फ़ाइल में बिल्ड का नियम तय किया जा सकता है. sapi_library बिल्ड के नियम से जुड़ा दस्तावेज़, बिल्ड के नियम पेज पर देखा जा सकता है.

नीचे दिए गए कोड स्निपेट में, zlib SAPI के उदाहरण के लिए sapi_library की परिभाषा दी गई है. lib एट्रिब्यूट का इस्तेमाल करके, Bazel को zlib लाइब्रेरी के लिए WORKSPACE फ़ाइल में देखने का निर्देश दिया जाता है.

sapi_library(
    name = "zlib-sapi",
    srcs = [],
    hdrs = [],
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@net_zlib//:zlib",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)

इसका नतीजा यह होता है कि सैंडबॉक्स की गई zlib लाइब्रेरी जनरेट हो जाती है. आउटपुट, SAPI ऑब्जेक्ट है. इसे होस्ट कोड में शामिल किया जा सकता है. साथ ही, इसका इस्तेमाल आरपीसी कॉल के ज़रिए सैंडबॉक्स की गई लाइब्रेरी से कम्यूनिकेट करने के लिए किया जा सकता है. इस उदाहरण में इस्तेमाल की गई सैंडबॉक्स नीति, डिफ़ॉल्ट नीति है.

3. होस्ट कोड लिखना या बदलना

अब जनरेट की गई SAPI लाइब्रेरी को होस्ट कोड में शामिल करने का समय है.

सैंडबॉक्स बनाना

सैंडबॉक्स ऑब्जेक्ट बनाने के लिए, sapi::Sandbox sandbox(sapi::zlib::zlib_sapi_embed_create()); का इस्तेमाल करें.

SAPI ऑब्जेक्ट को इंस्टैंशिएट करने के लिए, sapi::zlib::ZlibApi api(&sandbox); का इस्तेमाल करें. इससे सैंडबॉक्स किए गए फ़ंक्शन इस्तेमाल किए जा सकेंगे.

SAPI टाइप का इस्तेमाल करना

SAPI टाइप, C++ क्लास के तौर पर खास टाइप होते हैं. इन्हें SAPI उपलब्ध कराता है, क्योंकि कभी-कभी सामान्य C-टाइप काम नहीं करते.

SAPI टाइप का पहली बार इस्तेमाल, strm के एलान में किया गया है. यहां SAPI स्ट्रक्चर का इस्तेमाल किया गया है: sapi::v::Struct<sapi::zlib::z_stream> strm;

टेंप्लेट टाइप (sapi::zlib::z_stream), कोड का एक अच्छा उदाहरण है. यह कोड, बिल्ड रूल के ज़रिए अपने-आप जनरेट होता है.

ज़्यादा जानकारी के लिए, वैरिएबल पेज देखें.

एपीआई कॉल करना

defalteInit_, deflate या deflateEnd को कॉल करने के लिए, SAPI ऑब्जेक्ट का इस्तेमाल करें. अगर आपको ‘बदलाव करें' अप्रोच का इस्तेमाल करना है, तो आपको यह पक्का करना होगा कि फ़ंक्शन पैरामीटर, अनुमानित वैल्यू से मेल खाते हों.

zlib उदाहरण में हर कॉल का उदाहरण:

  • api.deflateInit_(strm.PtrBoth(), Z_DEFAULT_COMPRESSION,
    version.PtrBefore(), sizeof(sapi::zlib::z_stream));
  • api.deflate(strm.PtrBoth(), flush);
  • api.deflateEnd(strm.PtrBoth()).IgnoreError();

SAPI Transactions का इस्तेमाल करना

SAPI, होस्ट कोड को सैंडबॉक्स की गई लाइब्रेरी से अलग करता है. साथ ही, कॉल करने वाले को डेटा प्रोसेस करने के उन अनुरोधों को फिर से शुरू करने या रद्द करने की सुविधा देता है जिनमें समस्या आ रही है. SAPI Transaction, एक कदम आगे बढ़कर काम करता है. यह उन प्रोसेस को अपने-आप दोहराता है जो पूरी नहीं हो सकीं.

ज़्यादा जानकारी के लिए, SAPI लेन-देन वाला पेज देखें.

उदाहरण

उदाहरण में, आपको कुछ लाइब्रेरी मिल सकती हैं. इन्हें SAPI टीम ने पहले से ही तैयार किया है.