İşlem Grafiği Sorgusu (sorgu)

Sorun bildir Kaynağı görüntüle Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

aquery komutu, derleme grafiğinizdeki işlemler için sorgu oluşturmanıza olanak tanır. Analiz sonrası yapılandırılmış hedef grafiğinde çalışır ve işlemler, yapılar ve bunların ilişkileri hakkında bilgi verir.

aquery, Yapılandırılmış Hedef Grafiği'nden oluşturulan İşlemlerin/Öğelerin özellikleriyle ilgilendiğinizde kullanışlıdır. Örneğin, çalıştırılan gerçek komutlar ve bunların girişleri/çıkışları/kısaltmaları.

Araç, çeşitli komut satırı seçeneklerini kabul eder. Özellikle aquery komutu, normal bir Bazel derlemesinin üzerinde çalışır ve derleme sırasında kullanılabilen seçenekler grubunu devralır.

Geleneksel query, siblings, buildfiles ve tests cihazlarda da kullanılabilen işlevleri destekler.

Örnek bir aquery çıkışı (ayrıntılar olmadan):

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

Temel söz dizimi

aquery söz diziminin basit bir örneği aşağıda verilmiştir:

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

Sorgu ifadesi (tırnak içinde) şunlardan oluşur:

  • aquery_function(...): aquery'a özgü işlevler. Daha fazla bilgiyi aşağıda bulabilirsiniz.
  • function(...): Geleneksel query olarak standart işlevler.
  • //target, ilgilenilen hedefin etiketidir.
# 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))'

Sorgu işlevlerini kullanma

Üç aquery işlevi vardır:

  • inputs: İşlemleri girişlere göre filtreleyin.
  • outputs: işlemleri çıktılara göre filtreleme
  • mnemonic: işlemleri hafıza tekniğine göre filtreleme

expr ::= inputs(word, expr)

inputs operatörü, expr oluşturmaktan kaynaklanan işlemleri döndürür. Bu işlemlerin giriş dosya adları, word tarafından sağlanan normal ifadeyle eşleşir.

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

outputs ve mnemonic işlevleri benzer bir söz dizimine sahiptir.

Ayrıca, AND işlemini gerçekleştirmek için işlevleri birleştirebilirsiniz. Örneğin:

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

Yukarıdaki komut, //src/target_a oluşturma işlemine dahil olan ve anımsatıcıları "Cpp.*" ile eşleşen, girişleri ise ".*cpp" ve "foo.*" kalıplarıyla eşleşen tüm işlemleri bulur.

Üretilen söz dizimi hatası örneği:

        $ 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))

Seçenekler

Derleme seçenekleri

aquery, normal bir Bazel derlemesinin üzerinde çalışır ve bu nedenle derleme sırasında kullanılabilen seçenekler kümesini devralır.

Sorgu seçenekleri

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

Varsayılan çıkış biçimi (text) kullanıcı tarafından okunabilir. Makine tarafından okunabilir biçim için proto, textproto veya jsonproto'ü kullanın. Proto mesajı analysis.ActionGraphContainer.

--include_commandline, default=true

Çıkışta işlem komut satırlarının içeriğini (büyük olabilir) içerir.

--include_artifacts, default=true

Çıktıda işlem giriş ve çıkışlarının adlarını içerir (büyük olabilir).

--include_aspects, default=true

Çıkışa Aspect tarafından oluşturulan işlemlerin dahil edilip edilmeyeceği.

--include_param_files, default=false

Komutta kullanılan param dosyalarının içeriğini ekleyin (büyük olabilir).

--include_file_write_contents, default=false

actions.write() işlemi için dosya içeriklerini ve SourceSymlinkManifest işlemi için bildirim dosyasının içeriklerini ekleyin. Dosya içerikleri, file_contents alanında --output=xxxproto ile birlikte döndürülür. --output=text ile çıkışta FileWriteContents: [<base64-encoded file contents>] satır var

--skyframe_state, default=false

Ek analiz yapmadan Skyframe'den işlem grafiğini boşaltın.

Diğer araçlar ve özellikler

Skyframe'in durumuna göre sorgulama

Skyframe, Bazel'in değerlendirme ve artımlılık modelidir. Skyframe, Bazel sunucusunun her örneğinde Analiz aşamasının önceki çalıştırmalarından oluşturulan bağımlılık grafiğini depolar.

Bazı durumlarda, Skyframe'deki İşlem Grafiği'ne sorgu göndermek faydalı olur. Örnek bir kullanım alanı:

  1. bazel build //target_a çalıştırma
  2. bazel build //target_b çalıştırma
  3. foo.out dosyası oluşturuldu.

Bazel kullanıcısı olarak foo.out öğesinin //target_a veya //target_b oluşturma işleminden mi oluşturulduğunu belirlemek istiyorum.

bazel aquery 'outputs("foo.out", //target_a)' ve bazel aquery 'outputs("foo.out", //target_b)' komutları çalıştırılarak foo.out oluşturmaktan sorumlu işlem ve dolayısıyla hedef belirlenebilir. Ancak daha önce oluşturulan farklı hedeflerin sayısı 2'den fazla olabilir. Bu da birden fazla aquery komut çalıştırmayı zorlaştırır.

Alternatif olarak --skyframe_state işareti kullanılabilir:

  # 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 moduyla aquery, Skyframe'in Bazel örneğinde tuttuğu İşlem Grafiği'nin içeriğini alır, (isteğe bağlı olarak) üzerinde filtreleme yapar ve analiz aşamasını yeniden çalıştırmadan içeriği çıkarır.

Dikkat edilmesi gereken noktalar

Çıkış biçimi

--skyframe_state şu anda yalnızca --output=proto ve --output=textproto için kullanılabilir.

Hedef etiketlerin sorgu ifadesine dahil edilmemesi

Şu anda --skyframe_state, hedeflerden bağımsız olarak Skyframe'de bulunan tüm işlem grafiğini sorgular. Sorguda hedef etiketin --skyframe_state ile birlikte belirtilmesi söz dizimi hatası olarak kabul edilir:

  # 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 çıkışlarını karşılaştırma

aquery_differ aracını kullanarak iki farklı aquery çağrısının çıkışlarını karşılaştırabilirsiniz. Örneğin, kural tanımınızda bazı değişiklikler yaptığınızda ve çalıştırılan komut satırlarının değişmediğini doğrulamak istediğinizde. aquery_differ bu amaç için kullanılan araçtır.

Araç, bazelbuild/bazel deposunda kullanılabilir. Bu aracı kullanmak için kod deposunu yerel makinenize klonlayın. Örnek kullanım:

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

Yukarıdaki komut, before ve after aquery çıkışları arasındaki farkı döndürür: hangi işlemler birinde varken diğerinde yoktu, hangi işlemlerin her aquery çıkışında farklı komut satırı/girişleri var, ...). Yukarıdaki komutun çalıştırılmasının sonucu şu olur:

  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/
    ...

Komut seçenekleri

--before, --after: Karşılaştırılacak aquery çıkış dosyaları

--input_type=(proto|text_proto), default=proto: Giriş dosyalarının biçimi. proto ve textproto aquery çıkışı için destek sağlanır.

--attrs=(cmdline|inputs), default=cmdline: Karşılaştırılacak işlemlerin özellikleri.

En-boy oranı

Görünümlerin birbirinin üzerine uygulanması mümkündür. Bu yönler tarafından oluşturulan işlemin aquery çıkışı, daha sonra Yön yolu'nu (işlemi oluşturan hedefe uygulanan yönlerin sırası) içerir.

Özellikten özelliğe örneği:

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

ti, bağımlılarına ai yönünü uygulayan ri kuralının hedefi olsun.

a2'nin t0 hedefine uygulandığında X işlemini oluşturduğunu varsayalım. X işlemi için bazel aquery --include_aspects 'deps(//t2)' metin çıkışı şu şekilde olur:

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

Bu, X işleminin, a1(t0) üzerine uygulanan a2 Aspect'i tarafından oluşturulduğu anlamına gelir. Burada a1(t0), t0 hedefi üzerine uygulanan a1 Aspect'inin sonucudur.

Her AspectDescriptor aşağıdaki biçimdedir:

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

AspectClass, Aspect sınıfının adı (yerel Aspect'ler için) veya bzl_file%aspect_name (Starlark Aspect'leri için) olabilir. AspectDescriptor, bağımlılık grafiğinin topolojik sırasına göre sıralanır.

JSON profiliyle bağlantı oluşturma

aquery, bir derlemede çalıştırılan işlemler (neden çalıştırıldıkları, girişleri/çıkışları) hakkında bilgi sağlarken JSON profili, bu işlemlerin zamanlaması ve süresi hakkında bilgi verir. Bu iki bilgi grubu, ortak bir payda aracılığıyla (bir işlemin birincil çıktısı) birleştirilebilir.

JSON profiline işlemlerin çıkışlarını eklemek için profili --experimental_include_primary_output --noslim_profile ile oluşturun. İnce profiller, birincil çıktıların dahil edilmesiyle uyumlu değildir. Bir işlemin birincil çıkışı, aquery tarafından varsayılan olarak dahil edilir.

Şu anda bu iki veri kaynağını birleştirmek için standart bir araç sunmuyoruz ancak yukarıdaki bilgileri kullanarak kendi komut dosyanızı oluşturabilirsiniz.

Bilinen sorunlar

Paylaşılan işlemleri işleme

Bazen işlemler, yapılandırılmış hedefler arasında paylaşılır.

Yürütme aşamasında, bu paylaşılan işlemler tek bir işlem olarak kabul edilir ve yalnızca bir kez yürütülür. Ancak aquery, ön yürütme ve analiz sonrası işlem grafiğinde çalışır. Bu nedenle, bunları çıkış yapıtları tam olarak aynı execPath olan ayrı işlemler olarak ele alır. Bu nedenle, eşdeğer yapılar yinelenmiş olarak görünür.

Aquery ile ilgili sorunların/planlanan özelliklerin listesini GitHub'da bulabilirsiniz.

SSS

Bir giriş dosyasının içeriği değişse bile ActionKey aynı kalır.

Bir sorgu bağlamında ActionKey, ActionAnalysisMetadata#getKey'den alınan String değerini ifade eder:

  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.

Bu, giriş dosyalarının içeriğindeki değişiklikleri hariç tutar ve RemoteCacheClient#ActionKey ile karıştırılmamalıdır.

Güncellemeler

Sorunlar veya özellik istekleri için lütfen buradan sorun kaydı oluşturun.