כללי Workspace

הכללים ב-Workspace משמשים למשיכת תלויים חיצוניים, בדרך כלל קוד מקור שנמצא מחוץ למאגר הראשי.

הערה: בנוסף לכללים של סביבת העבודה המקורית, Bazel מטמיעה גם כללים שונים של Starlark workspace, במיוחד בכל הנוגע לטיפול במאגרי Git או בארכיונים שמתארחים באינטרנט.

כללים

• קישור
• local_repository
• new_local_repository

קישור

bind(name, actual, compatible_with, deprecation, distribs, features, licenses, restricted_to, tags, target_compatible_with, testonly, visibility)

אזהרה: לא מומלץ להשתמש בדומיין bind(). &הסבר:כדאי להסיר את הקישור&לדיון ארוך על הבעיות והחלופות שלו. כדאי לשים לב במיוחד לשימוש בrepo_mapping מאפייני מאגר.

אזהרה: לא ניתן להשתמש באפליקציה select() בbind(). לפרטים נוספים, ראו שאלות נפוצות בנושא מאפיינים ניתנים להגדרה.

הוספת יעד בחבילה של //external.

החבילה //external אינה חבילה "normal" חבילה: אין תיקייה חיצונית/ , ולכן אפשר לחשוב עליה כ- "וירטואלית &"שכוללת את כל היעדים המשויכים.

דוגמאות

כדי להוסיף יעד, bind צריך לציין אותו בקובץ WORKSPACE. לדוגמה, נניח שיש יעד java_library בשם //third_party/javacc-v2. אפשר לתת כינוי זה על ידי הוספת הערכים הבאים לקובץ WORKSPACE:

bind(
    name = "javacc-latest",
    actual = "//third_party/javacc-v2",
)

עכשיו היעדים יכולים להיות תלויים ב-//external:javacc-latest במקום ב-//third_party/javacc-v2. אם Javacc-v3 ישוחרר, אפשר לעדכן את הכלל bind וכל קובצי BUILD בהתאם ל-//external:javacc-latest יהיו תלויים עכשיו ב-Javacc-v3 ללא צורך בעריכה.

אפשר גם להשתמש בתהליך הקישור כדי להפוך יעדים במאגרים חיצוניים לזמינים לסביבת העבודה שלך. לדוגמה, אם קיים מאגר מרוחק בשם @my-ssl שיובא בקובץ WORKSPACE ויש לו יעד cc_library //src:openssl-lib, ניתן ליצור כינוי עבור היעד באמצעות bind:

bind(
    name = "openssl",
    actual = "@my-ssl//src:openssl-lib",
)

לאחר מכן, בקובץ BUILD בסביבת העבודה שלכם, תוכלו להשתמש ביעד המקושר כך:

cc_library(
    name = "sign-in",
    srcs = ["sign_in.cc"],
    hdrs = ["sign_in.h"],
    deps = ["//external:openssl"],
)

ב-sign_in.cc וב-sign_in.h, אפשר להפנות לקובצי הכותרת שנחשפים על ידי //external:openssl באמצעות הנתיב שלהם, ביחס לשורש המאגר שלהם. לדוגמה, אם ההגדרה של הכלל @my-ssl//src:openssl-lib נראית כך:

cc_library(
    name = "openssl-lib",
    srcs = ["openssl.cc"],
    hdrs = ["openssl.h"],
)

לאחר מכן, הכותרות של sign_in.cc& עשויה להיראות כך:

#include "sign_in.h"
#include "src/openssl.h"

ארגומנטים

מאפיינים
name	Name; required שם ייחודי ליעד הזה.
actual	Label; optional המטרה של כינוי. היעד הזה חייב להיות קיים, אבל הוא יכול להיות כל סוג של כלל (כולל כריכה). אם מאפיין זה לא ייכלל, הכללים הנוגעים ליעד הזה ב-//external פשוט לא יראו את קצה התלות הזה. לתשומת ליבך: זה שונה מהשמטת הכלל bind: שגיאה אם אין //external תלות{0}bind.

local_repository

local_repository(name, path, repo_mapping)

המדיניות הזו מאפשרת לקשר יעדים מספרייה מקומית. פירוש הדבר הוא שהמאגר הנוכחי יכול להשתמש ביעדים שהוגדרו בספרייה האחרת הזו. למידע נוסף, עיינו בקטע קישור.

דוגמאות

נניח שמאגר הנתונים הנוכחי הוא לקוח צ'אט, שעבר ספרייה ~/chat-app. הוא רוצה להשתמש בספריית SSL המוגדרת במאגר אחר: ~/ssl. לספריית SSL יש יעד //src:openssl-lib.

כדי להוסיף תלות ביעד הזה, מוסיפים את השורות הבאות: ~/chat-app/WORKSPACE:

local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
)

כדי לציין את הספרייה, תלות ביעדים צריכה להיות @my-ssl//src:openssl-lib.

ארגומנטים

מאפיינים
name	Name; required שם ייחודי ליעד הזה.
path	String; required הנתיב לספריית המאגר המקומית. זה חייב להיות נתיב לספרייה שמכילה את קובץ WORKSPACE של המאגר. הנתיב יכול להיות מוחלט או יחסי לקובץ ה-WORKSPACE# של המאגר הראשי.
repo_mapping	Dictionary: String -> String; optional מילון משם המאגר המקומי לשם מאגר גלובלי. ההגדרה מאפשרת שליטה ברזולוציית התלות של סביבות עבודה בהתאם לתלויות של מאגר הנתונים הזה. לדוגמה, רשומה "@foo": "@bar" מצהירה שבכל זמן המאגר הזה תלוי ב-"@foo" (כמו תלות ב-"@foo//some:target"), הוא צריך לפתור את התלות בתוך "@bar" בכל העולם ("@bar//some:target").

new_local_repository

new_local_repository(name, build_file, build_file_content, path, repo_mapping, workspace_file, workspace_file_content)

מאפשרת להפוך ספרייה מקומית למאגר Bazel. פירוש הדבר הוא שהמאגר הנוכחי יכול להגדיר יעדים ולהשתמש בהם מכל מקום במערכת הקבצים.

הכלל הזה יוצר מאגר של Bazel על ידי יצירה של קובץ WORKSPACE וספריית משנה שמכילה קישורי קישור לקובץ BUILD ולנתיב שסופקו. קובץ ה-build צריך ליצור יעדים ביחס לקובץ path. עבור ספריות שכבר כוללות קובץ WORKSPACE וקובץ BUILD, ניתן להשתמש בכלל local_repository.

דוגמאות

נניח שמאגר הנתונים הנוכחי הוא לקוח צ'אט, שעבר רוטציה לספרייה ~/chat-app. הוא רוצה להשתמש בספריית SSL המוגדרת בספרייה אחרת: ~/ssl.

המשתמש יכול להוסיף תלות על ידי יצירת קובץ BUILD עבור ספריית ה-SSL (~/chat-app/BUILD.my-ssl) המכיל:

java_library(
    name = "openssl",
    srcs = glob(['*.java'])
    visibility = ["//visibility:public"],
)

הוא יוכל להוסיף את השורות הבאות אל ~/chat-app/WORKSPACE:

new_local_repository(
    name = "my-ssl",
    path = "/home/user/ssl",
    build_file = "BUILD.my-ssl",
)

הפעולה הזו תיצור מאגר @my-ssl שיקשר אל /home/user/ssl. היעדים יכולים להיות תלויים בספרייה הזו. לשם כך, מוסיפים @my-ssl//:openssl לתלויות ביעד.

ניתן להשתמש ב-new_local_repository גם כדי לכלול קבצים בודדים, לא רק ספריות. לדוגמה, נניח שהיה לכם קובץ בשם /home/username/Downloads/piano.gar. אפשר להוסיף לקובץ הזה ב-WORKSPACE רק את הקובץ הבא:

new_local_repository(
    name = "piano",
    path = "/home/username/Downloads/piano.jar",
    build_file = "BUILD.piano",
)

וייצירת קובץ BUILD.piano הבא:

java_import(
    name = "play-music",
    jars = ["piano.jar"],
    visibility = ["//visibility:public"],
)

לאחר מכן, ייתכן שיעדים מסוימים יתבססו על @piano//:play-music כדי להשתמש ב-פסנתר.gar.

ארגומנטים

מאפיינים
name	Name; required שם ייחודי ליעד הזה.
build_file	String; optional קובץ שישמש כקובץ BUILD עבור הספרייה הזו. יש לציין build_file או build_file_content. המאפיין הזה הוא תווית יחסית לסביבת העבודה הראשית. אין צורך שהשם של הקובץ יהיה BUILD, אבל הוא יכול להיות. (משהו כמו BUILD.new-repo-name עשוי להתאים להבחנה בין קובצי ה-BUILD למאגר.
build_file_content	String; optional התוכן לקובץ BUILD עבור מאגר הנתונים הזה. יש לציין build_file או build_file_content.
path	String; required נתיב במערכת הקבצים המקומית. זה יכול להיות מוחלט או יחסי לקובץ ה-WORKSPACE של המאגר הראשי.
repo_mapping	Dictionary: String -> String; optional מילון משם המאגר המקומי לשם מאגר גלובלי. ההגדרה מאפשרת שליטה ברזולוציית התלות של סביבות עבודה בהתאם לתלויות של מאגר הנתונים הזה. לדוגמה, רשומה "@foo": "@bar" מצהירה שבכל זמן המאגר הזה תלוי ב-"@foo" (כמו תלות ב-"@foo//some:target"), הוא צריך לפתור את התלות בתוך "@bar" בכל העולם ("@bar//some:target").
workspace_file	String; optional הקובץ הזה ישמש כקובץ WORKSPACE עבור המאגר הזה. אפשר לציין את workspace_file או את workspace_file_content, אך לא את שניהם. המאפיין הזה הוא תווית יחסית לסביבת העבודה הראשית. אין צורך שהשם של הקובץ יהיה WORKSPACE, אבל הוא יכול להיות. (משהו כמו WORKSPACE.new-repo-name עשוי לעבוד היטב כדי להבדיל אותו מקובצי ה-WORKSPACE של המאגר.)
workspace_file_content	String; optional התוכן לקובץ WORKSPACE עבור המאגר הזה. אפשר לציין את workspace_file או את workspace_file_content, אך לא את שניהם.