طلب رسم بياني للإجراء (aquery)

يسمح لك الأمر aquery بطلب بحث عن إجراءات في الرسم البياني للإصدار. تعمل هذه الأداة على "الرسم البياني المستهدَف" الذي تم ضبطه بعد التحليل، وتعرض معلومات عن الإجراءات والعناصر، وعلاقاتها.

وتكون aquery مفيدة عندما تكون مهتمًا بخصائص العناصر/العناصر التي يتم إنشاؤها من "الرسم البياني المستهدَف الذي تم ضبطه". على سبيل المثال، يتم تشغيل الأوامر الفعلية والإدخالات/المخرجات/التذكيرات.

تقبل الأداة خيارات عديدة لسطر الأوامر. بشكل ملحوظ، يعمل أمر aquery على إصدار Bazel عادي ويكتسب مجموعة من الخيارات المتاحة أثناء الإصدار.

وتوفّر هذه السياسة مجموعة الوظائف نفسها التي تتوفّر أيضًا query التقليدية وsiblings وbuildfiles وtests.

مثال على الناتج aquery (بدون تفاصيل محدّدة):

$ bazel aquery 'deps(//some:label)'
action 'Writing file some_file_name'
  Mnemonic: ...
  Target: ...
  Configuration: ...
  ActionKey: ...
  Inputs: [...]
  Outputs: [...]

البنية الأساسية

في ما يلي مثال بسيط على بنية aquery:

bazel aquery "aquery_function(function(//target))"

يتألف تعبير طلب البحث (بين علامات الاقتباس) مما يلي:

• aquery_function(...): دوال خاصة بـ aquery. يمكنك الاطّلاع على المزيد من التفاصيل أدناه.
• function(...): الدوال العادية كما هي query التقليدية.
• //target هو التصنيف للهدف المعني.

# aquery examples:
# Get the action graph generated while building //src/target_a
$ bazel aquery '//src/target_a'

# Get the action graph generated while building all dependencies of //src/target_a
$ bazel aquery 'deps(//src/target_a)'

# Get the action graph generated while building all dependencies of //src/target_a
# whose inputs filenames match the regex ".*cpp".
$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'

استخدام دوال طلب البحث

هناك ثلاث وظائف aquery:

• inputs: فلترة الإجراءات حسب الإدخالات.
• outputs: فلترة الإجراءات حسب النتائج
• mnemonic: فلترة الإجراءات حسب الاختصار

expr ::= inputs(word, expr)

يعرض عامل التشغيل inputs الإجراءات التي تم إنشاؤها من المبنى expr، الذي تتطابق أسماء ملفات الإدخال معه مع التعبير العادي الذي يوفره word.

$ bazel aquery 'inputs(".*cpp", deps(//src/target_a))'

تشترك الدالتان outputs وmnemonic في بنية مشابهة.

يمكنك أيضًا الجمع بين الدوال لتنفيذ العملية AND. مثلاً:

  $ bazel aquery 'mnemonic("Cpp.*", (inputs(".*cpp", inputs("foo.*", //src/target_a))))'

سيتناول الأمر أعلاه كل الإجراءات التي تم تنفيذها في إنشاء //src/target_a، التي تتطابق معها الاختصارات مع "Cpp.*" والإدخالات التي تطابق النمطَين ".*cpp" و"foo.*".

في ما يلي مثال على الخطأ الذي تم إصداره في البنية:

        $ bazel aquery 'deps(inputs(".*cpp", //src/target_a))'
        ERROR: aquery filter functions (inputs, outputs, mnemonic) produce actions,
        and therefore can't be the input of other function types: deps
        deps(inputs(".*cpp", //src/target_a))

الخيارات

خيارات الإصدار

يعمل aquery على إصدار Bazel عادي، ويكتسب مجموعة الخيارات المتاحة خلال الإصدار.

خيارات طلب البحث

--output=(text|summary|proto|jsonproto|textproto), default=text

تنسيق الناتج التلقائي (text) يمكن للمستخدمين قراءته، استخدِم proto أو textproto أو jsonproto لتنسيق يمكن للآلة قراءته. رسالة Proto هي analysis.ActionGraphContainer.

--include_commandline, default=true

يتضمن محتوى أسطر أوامر الإجراء في الإخراج (المحتمل أن يكون كبيرًا).

--include_artifacts, default=true

تشمل أسماء مدخلات الإجراء ومخرجاته (الناتج المحتمل).

--include_aspects, default=true

ما إذا كان سيتم تضمين الإجراءات التي تم إنشاؤها بواسطة Aspect في الإخراج.

--include_param_files, default=false

أدرِج محتوى ملفات المعلَمات المستخدمة في الأمر (يُحتمل أن يكون كبيرًا).

--include_file_write_contents, default=false

أدرِج محتوى الملف للإجراء actions.write() ومحتوى الملف المرتبط للإجراء SourceSymlinkManifest. ويتم عرض محتوى الملف في الحقل file_contents بالقيمة --output=xxxproto. من خلال --output=text، تشتمل المخرجات على FileWriteContents: [<base64-encoded file contents>] سطر

--skyframe_state, default=false

بدون إجراء تحليل إضافي، تفريغ الرسم البياني للحركة من Skyframe.

الأدوات والميزات الأخرى

الاستعلام عن حالة Skyframe

Skyframe هي نموذج التقييم والزيادة في Bazel. في كل نسخة افتراضية من خادم Bazel، يخزّن Skyframe الرسم البياني للتبعية الذي تم إنشاؤه من المراحل السابقة لمراحل التحليل.

في بعض الحالات، من المفيد طلب البحث عن الرسم البياني للحركة على Skyframe. من أمثلة حالات الاستخدام ما يلي:

1. السباق bazel build //target_a
2. السباق bazel build //target_b
3. تم إنشاء الملف foo.out.

بصفتي مستخدمًا في Bazel، أريد تحديد ما إذا تم إنشاء foo.out من المبنى //target_a أو //target_b.

يمكن البدء في استخدام bazel aquery 'outputs("foo.out", //target_a)' وbazel aquery 'outputs("foo.out", //target_b)' لتحديد الإجراء المسؤول عن إنشاء foo.out، وبالتالي تحقيق الهدف. ويمكن أن يكون عدد الاستهدافات المختلفة التي تم إنشاؤها في السابق أكبر من رقمَين، ما يجعل تشغيل الأمر aquery المتعدّد أمرًا مزعجًا.

يمكن استخدام العلامة --skyframe_state بدلاً من ذلك:

  # List all actions on Skyframe's action graph
  $ bazel aquery --output=proto --skyframe_state

  # or

  # List all actions on Skyframe's action graph, whose output matches "foo.out"
  $ bazel aquery --output=proto --skyframe_state 'outputs("foo.out")'

باستخدام الوضع --skyframe_state، تأخذ aquery محتوى الرسم البياني للحركة الذي يحافظ عليه Skyframe على مثيل Bazel، (اختياريًا) ويجري الفلترة عليه، ويُخرج المحتوى، بدون إعادة تشغيل مرحلة التحليل.

اعتبارات خاصة

تنسيق الناتج

--skyframe_state متاح حاليًا فقط لـ --output=proto و--output=textproto

عدم تضمين التصنيفات المستهدفة في تعبير طلب البحث

حاليًا، يرسل --skyframe_state طلب البحث عن الرسم البياني للإجراءات بالكامل الموجود في Skyframe، بغض النظر عن الأهداف. يُعدّ تحديد التصنيف المستهدَف في طلب البحث مع --skyframe_state خطأ في البنية:

  # WRONG: Target Included
  $ bazel aquery --output=proto --skyframe_state **//target_a**
  ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.

  # WRONG: Target Included
  $ bazel aquery --output=proto --skyframe_state 'inputs(".*.java", **//target_a**)'
  ERROR: Error while parsing '//target_a)': Specifying build target(s) [//target_a] with --skyframe_state is currently not supported.

  # CORRECT: Without Target
  $ bazel aquery --output=proto --skyframe_state
  $ bazel aquery --output=proto --skyframe_state 'inputs(".*.java")'

مقارنة مخرجات طلب البحث

يمكنك مقارنة مخرجات استدعاءَين مختلفَين لطلب البحث باستخدام الأداة aquery_differ. على سبيل المثال: عند إجراء بعض التغييرات على تعريف القاعدة والرغبة في التحقق من أن أسطر الأوامر التي يجري تشغيلها لم تتغير. aquery_differ هي الأداة اللازمة لذلك.

تتوفّر الأداة في المستودع bazelbuild/bazel. ولاستخدام هذا الجهاز، يمكنك نسخ المستودع إلى جهازك المحلي. مثال على الاستخدام:

  $ bazel run //tools/aquery_differ -- \
  --before=/path/to/before.proto \
  --after=/path/to/after.proto \
  --input_type=proto \
  --attrs=cmdline \
  --attrs=inputs

يعرض الأمر أعلاه الفرق بين مخرجات طلب البحث before وafter: الإجراءات التي كانت موجودة في أحدهما وليس الآخر، والإجراءات التي تحتوي على سطر/إدخالات أوامر مختلفة في كل نتيجة من طلبات البحث، ...). ستكون نتيجة تشغيل الأمر أعلاه:

  Aquery output 'after' change contains an action that generates the following outputs that aquery output 'before' change doesn't:
  ...
  /list of output files/
  ...

  [cmdline]
  Difference in the action that generates the following output(s):
    /path/to/abc.out
  --- /path/to/before.proto
  +++ /path/to/after.proto
  @@ -1,3 +1,3 @@
    ...
    /cmdline diff, in unified diff format/
    ...

خيارات الطلب

--before, --after: ملفات مخرجات طلب البحث المراد مقارنتها

--input_type=(proto|text_proto), default=proto: تنسيق ملفات الإدخال يتم توفير الدعم لإخراج طلب البحث proto وtextproto.

--attrs=(cmdline|inputs), default=cmdline: سمات الإجراءات المطلوب مقارنتها.

جانب إلى جانب

يمكن تطبيق الجوانب على بعضها البعض. ستحتوي نتيجة طلب البحث التي تم إنشاؤها من خلال هذه الجوانب على مسار العرض إلى الارتفاع، وهو تسلسل من "الجوانب" التي تم تطبيقها على الهدف الذي أدى إلى إنشاء الإجراء.

مثال على جانب العرض إلى الارتفاع:

  t0
  ^
  | <- a1
  t1
  ^
  | <- a2
  t2

دعك _تستهدف القاعدة _r، التي تطبق _a A على تبعياتها.

افترض أنّ a2 تنشئ الإجراء X عند تطبيقه على t0 المستهدف. نتيجة النص للإجراء bazel aquery --include_aspects 'deps(//t2)' هي:

  action ...
  Mnemonic: ...
  Target: //my_pkg:t0
  Configuration: ...
  AspectDescriptors: [//my_pkg:rule.bzl%**a2**(foo=...)
    -> //my_pkg:rule.bzl%**a1**(bar=...)]
  ...

وهذا يعني أن الإجراء X تم إنشاؤه بواسطة Aspect a2 وتم تطبيقه على a1(t0)، حيث a1(t0) كانت نتيجة a1 تم تطبيقها على t0.

يكون لكل AspectDescriptor التنسيق التالي:

  AspectClass([param=value,...])

قد يكون AspectClass هو اسم فئة Aspect (للمكوّنات الأصلية) أو bzl_file%aspect_name (بالنسبة إلى AJAST). يتم ترتيب AspectDescriptor بترتيب طوبوغرافي للرسم البياني التابع.

الربط بملف JSON الشخصي

على الرغم من أن طلب البحث يوفّر معلومات حول الإجراءات التي يتم تنفيذها في الإصدار (لماذا يتم تنفيذها، ومصادر الإدخال/الإخراج)، يُخبرنا الملف الشخصي بتنسيق JSON بوقت التنفيذ ومدته. من الممكن الجمع بين هاتين المجموعتين من المعلومات من خلال المقام المشترك: الإخراج الأساسي للإجراء.

لتضمين الإجراءات' والمخرجات في الملف الشخصي بتنسيق JSON، يمكنك إنشاء الملف الشخصي باستخدام --experimental_include_primary_output --noexperimental_slim_json_profile. لا تتوافق الملفات الشخصية رفيعة المستوى مع تضمين المخرجات الأساسية. يتم تضمين الإخراج الأساسي للإجراء مع طلب البحث بشكل تلقائي.

لا نوفّر حاليًا أداة أساسية لدمج مصدرَي البيانات هذين، ولكن من المفترض أن تتمكن من إنشاء نصك البرمجي الخاص بك باستخدام المعلومات الواردة أعلاه.

المشاكل المعروفة

التعامل مع الإجراءات المشتركة

في بعض الأحيان تتم مشاركة الإجراءات بين الاستهدافات التي تم ضبطها.

وفي مرحلة التنفيذ، يتم اعتبار هذه الإجراءات المشتركة كإجراء واحد ويتم تنفيذها مرة واحدة فقط. ومع ذلك، يعمل طلب البحث على التنفيذ قبل التنفيذ والرسم البياني للإجراءات بعد التحليل، وبالتالي يتعامل مع هذه الإجراءات مثل الإجراءات المنفصلة التي يكون لها عناصر الإخراج execPath نفسها تمامًا. ونتيجةً لذلك، يبدو أنّ العناصر المكافئة مكافئة.

يمكن العثور على قائمة بمشاكل طلب البحث/الميزات المخططة على GitHub.

الأسئلة الشائعة

يظل مفتاح العمل كما هو على الرغم من تغيير محتوى ملف الإدخال.

في سياق طلب البحث، يشير ActionKey إلى String التي تم الحصول عليها من ActionAnalysisMetadata#getKey:

  Returns a string encoding all of the significant behaviour of this Action that might affect the
  output. The general contract of `getKey` is this: if the work to be performed by the
  execution of this action changes, the key must change.

  ...

  Examples of changes that should affect the key are:

  - Changes to the BUILD file that materially affect the rule which gave rise to this Action.
  - Changes to the command-line options, environment, or other global configuration resources
      which affect the behaviour of this kind of Action (other than changes to the names of the
      input/output files, which are handled externally).
  - An upgrade to the build tools which changes the program logic of this kind of Action
      (typically this is achieved by incorporating a UUID into the key, which is changed each
      time the program logic of this action changes).
  Note the following exception: for actions that discover inputs, the key must change if any
  input names change or else action validation may falsely validate.

وهذا يستبعد التغييرات في محتوى ملفات الإدخال، ولا يمكن الخلط بينه وبين RemoteCacheClient#ActionKey.

آخر المعلومات

بالنسبة إلى أي مشاكل أو طلبات ميزات، يُرجى الإبلاغ عن مشكلة هنا.