Sorgu hızlı başlangıç kılavuzu

Bu eğitimde, hazır bir Bazel projesini kullanarak kodunuzdaki bağımlılıkları izlemek için Bazel ile nasıl çalışacağınız açıklanmaktadır.

Dil ve --output işareti ayrıntıları için Bazel sorgusu referansı ve Bazel sorgu referansı kılavuzlarına bakın. Komut satırına bazel help query veya bazel help cquery yazarak IDE'nizde yardım alın.

Hedef

Bu kılavuzda, projenizin dosya bağımlılıkları hakkında daha fazla bilgi edinmek için kullanabileceğiniz bir dizi temel sorgu açıklanmaktadır. Bu eğitim, Bazel ve BUILD dosyalarının işleyiş şekli hakkında temel düzeyde bilgi sahibi olan yeni Bazel geliştiricileri için hazırlanmıştır.

Ön koşullar

Henüz yapmadıysanız Bazel'i yükleyin. Bu eğitimde kaynak kontrolü için Git kullanılır. En iyi sonuçlar için Git'i de yükleyin.

Bağımlılık grafiklerini görselleştirmek için Graphviz adlı araç kullanılır. Bu aracı, adımları takip etmek için indirebilirsiniz.

Örnek projeyi alma

Ardından, tercih ettiğiniz komut satırı aracında aşağıdakileri çalıştırarak örnek uygulamayı Bazel'in Örnekler deposundan alın:

git clone https://github.com/bazelbuild/examples.git

Bu eğitim için örnek proje examples/query-quickstart dizinindedir.

Başlarken

Bazel sorguları nedir?

Sorgular, BUILD dosyaları arasındaki ilişkileri analiz ederek ve elde edilen çıkışı faydalı bilgiler açısından inceleyerek bir Bazel kod tabanı hakkında bilgi edinmenize yardımcı olur. Bu kılavuzda bazı temel sorgu işlevlerinin önizlemesi sunulmaktadır. Daha fazla seçenek için sorgu kılavuzuna bakın. Sorgular, büyük ölçekli projelerdeki bağımlılıklar hakkında bilgi edinmek için BUILD dosyalarında manuel olarak gezinmenize gerek kalmadan size yardımcı olur.

Sorgu çalıştırmak için komut satırı terminalinizi açıp şunu girin:

bazel query 'query_function'

Senaryo

Cafe Bazel ile şefi arasındaki ilişkiyi derinlemesine inceleyen bir senaryo düşünün. Bu kafe özel olarak pizza, mac ve peynir satar. Projenin nasıl yapılandırıldığına aşağıdan göz atabilirsiniz:

bazelqueryguide
├── BUILD
├── src
│   └── main
│       └── java
│           └── com
│               └── example
│                   ├── customers
│                   │   ├── Jenny.java
│                   │   ├── Amir.java
│                   │   └── BUILD
│                   ├── dishes
│                   │   ├── Pizza.java
│                   │   ├── MacAndCheese.java
│                   │   └── BUILD
│                   ├── ingredients
│                   │   ├── Cheese.java
│                   │   ├── Tomatoes.java
│                   │   ├── Dough.java
│                   │   ├── Macaroni.java
│                   │   └── BUILD
│                   ├── restaurant
│                   │   ├── Cafe.java
│                   │   ├── Chef.java
│                   │   └── BUILD
│                   ├── reviews
│                   │   ├── Review.java
│                   │   └── BUILD
│                   └── Runner.java
└── WORKSPACE

Bu eğitim boyunca, aksi belirtilmediği sürece ihtiyacınız olan bilgileri bulmak için BUILD dosyalarına bakmamaya çalışın ve bunun yerine yalnızca sorgu işlevini kullanın.

Proje, bir kafeyi oluşturan farklı paketlerden oluşur. Bunlar şu şekilde ayrılır: restaurant, ingredients, dishes, customers ve reviews. Bu paketlerdeki kurallar, kafenin farklı bileşenlerini çeşitli etiketler ve bağımlılıklarla tanımlar.

Derleme çalıştırma

Bu projede, kafenin menüsünü yazdırmak için yürütebileceğiniz Runner.java içinde bir ana yöntem bulunur. bazel build komutuyla Bazel'i kullanarak projeyi derleyin ve hedefin runner olarak adlandırıldığını belirtmek için : kullanın. Hedeflere nasıl referans vereceğinizi öğrenmek için hedef adlarına bakın.

Bu projeyi derlemek için aşağıdaki komutu bir terminale yapıştırın:

bazel build :runner

Derleme başarılı olursa çıkışınız şuna benzer bir görünümde olacaktır.

INFO: Analyzed target //:runner (49 packages loaded, 784 targets configured).
INFO: Found 1 target...
Target //:runner up-to-date:
  bazel-bin/runner.jar
  bazel-bin/runner
INFO: Elapsed time: 16.593s, Critical Path: 4.32s
INFO: 23 processes: 4 internal, 10 darwin-sandbox, 9 worker.
INFO: Build completed successfully, 23 total actions

Uygulama başarıyla oluşturulduktan sonra aşağıdaki komutu yapıştırarak uygulamayı çalıştırın:

bazel-bin/runner

--------------------- MENU -------------------------

Pizza - Cheesy Delicious Goodness
Macaroni & Cheese - Kid-approved Dinner

----------------------------------------------------

Bu işlem, kısa bir açıklamayla birlikte verilen menü öğelerinin listesini gösterir.

Hedefleri keşfetme

Projede, malzemeler ve yemekler kendi paketlerinde listelenir. Bir paketin kurallarını görüntülemek için sorgu kullanmak istiyorsanız bazel query package/…

Bu durumda, aşağıdaki sorguyu çalıştırarak bu kafenin sunduğu yemekleri ve malzemeleri incelemek için bu özelliği kullanabilirsiniz:

bazel query //src/main/java/com/example/dishes/...

bazel query //src/main/java/com/example/ingredients/...

Malzeme paketinin hedeflerini sorgularsanız çıkış aşağıdaki gibi görünmelidir:

//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/ingredients:dough
//src/main/java/com/example/ingredients:macaroni
//src/main/java/com/example/ingredients:tomato

Bağımlılıkları bulma

Koşucu, koşmak için hangi hedeflere güveniyor?

Dosya sistemine girmeden (büyük projeler için uygun olmayabilir) projenizin yapısına daha ayrıntılı bir şekilde göz atmak istediğinizi varsayalım. Cafe Bazel hangi kuralları kullanıyor?

Bu örnekte olduğu gibi koşucu hedefiniz runner ise şu komutu çalıştırarak hedefin temel bağımlılıklarını keşfedin:

bazel query --noimplicit_deps "deps(target)"

bazel query --noimplicit_deps "deps(:runner)"

//:runner
//:src/main/java/com/example/Runner.java
//src/main/java/com/example/dishes:MacAndCheese.java
//src/main/java/com/example/dishes:Pizza.java
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:Cheese.java
//src/main/java/com/example/ingredients:Dough.java
//src/main/java/com/example/ingredients:Macaroni.java
//src/main/java/com/example/ingredients:Tomato.java
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/ingredients:dough
//src/main/java/com/example/ingredients:macaroni
//src/main/java/com/example/ingredients:tomato
//src/main/java/com/example/restaurant:Cafe.java
//src/main/java/com/example/restaurant:Chef.java
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

Çoğu durumda, belirli bir hedefin çıktı bağımlılıklarını ayrı ayrı görmek için deps() sorgu işlevini kullanın.

Bağımlılık grafiğini görselleştirme (isteğe bağlı)

Bu bölümde, belirli bir sorgunun bağımlılık yollarını nasıl görselleştirebileceğiniz açıklanmaktadır. Graphviz, yolu düzleştirilmiş bir liste yerine yönlendirilmiş döngüsel olmayan bir grafik resmi olarak görmenize yardımcı olur. Çeşitli --output komut satırı seçeneklerini kullanarak Bazel sorgu grafiğinin görünümünü değiştirebilirsiniz. Seçenekler için Çıkış Biçimleri bölümüne bakın.

İstediğiniz sorguyu çalıştırarak başlayın ve aşırı araç bağımlılığını kaldırmak için --noimplicit_deps işaretini ekleyin. Ardından, çıkış işaretiyle sorguyu takip edin ve grafiğin metin gösterimini oluşturmak için grafiği graph.in adlı bir dosyada depolayın.

Hedef :runner'ün tüm bağımlılıkları için arama yapmak ve çıktıyı grafik olarak biçimlendirmek için:

bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph.in

Bu işlem, derleme grafiğinin metin temsili olan graph.in adlı bir dosya oluşturur. Graphviz, png oluşturmak için metni görselleştirmeye dönüştüren bir araç olan dot 'i kullanır:

dot -Tpng < graph.in > graph.png

graph.png dosyasını açarsanız aşağıdakine benzer bir görünüm görürsünüz. Aşağıdaki grafik, bu kılavuzda önemli yol ayrıntılarını daha net hale getirmek için basitleştirilmiştir.

Bu işlem, bu kılavuz boyunca farklı sorgu işlevlerinin çıktılarını görmek istediğinizde işinize yarayacaktır.

Ters bağımlılıkları bulma

Bunun yerine, hangi diğer hedeflerin kullandığını analiz etmek istediğiniz bir hedefiniz varsa belirli bir kurala bağlı hedefleri incelemek için sorgu kullanabilirsiniz. Buna "ters bağımlılık" denir. rdeps()'ü kullanmak, aşina olmadığınız bir kod tabanındaki bir dosyayı düzenlerken faydalı olabilir ve size bu dosyaya bağlı diğer dosyaları bilmeden bozmaktan kurtarabilir.

Örneğin, cheese bileşeninde bazı düzenlemeler yapmak istiyorsunuz. Cafe Bazel'de sorun yaşamamak için hangi yemeklerin cheese kullandığını kontrol etmeniz gerekir.

Belirli bir hedefe/pakete bağlı hedefleri görmek için rdeps(universe_scope, target) değerini kullanabilirsiniz. rdeps() sorgu işlevi, en az iki bağımsız değişken alır: bir universe_scope - ilgili dizin ve bir target. Bazel, sağlanan universe_scope içinde hedefin ters bağımlılıkları arar. rdeps() operatörü, isteğe bağlı üçüncü bağımsız değişkeni kabul eder: Aramanın derinliğinin üst sınırını belirten tam sayı bir düz sayı.

Projenin tamamının kapsamı olan "//…" içinde hedef cheese'nin ters bağımlılıklarını aramak için şu komutu çalıştırın:

bazel query "rdeps(universe_scope, target)"

ex) bazel query "rdeps(//... , //src/main/java/com/example/ingredients:cheese)"

//:runner
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

Sorgu sonucu, hem pizza hem de makarna için peynirin kullanıldığını gösterir. Ne sürpriz!

Etiketlere göre hedef bulma

Amir ve Jenny, Bazel Cafe'ye girer. Bu kişiler hakkında adları dışında hiçbir bilgi yoktur. Neyse ki siparişleri "customers" BUILD dosyasında etiketlenmiş. Bu etikete nasıl erişebilirsiniz?

Geliştiriciler, genellikle test amacıyla Bazel hedeflerini farklı tanımlayıcılarla etiketleyebilirler. Örneğin, testlerdeki etiketler, özellikle de çalışma zamanında ek açıklama özelliği bulunmayan C++ ve Python testleri için bir testin hata ayıklama ve yayınlama işleminizdeki rolünü ek açıklamayla belirtebilir. Etiketler ve boyut öğeleri kullanmak, kod tabanının check-in politikasına göre test paketleri oluşturma konusunda esneklik sağlar.

Bu örnekte, etiketler menü öğelerini temsil etmek için pizza veya macAndCheese değerlerinden biridir. Bu komut, belirli bir pakette tanımlayıcınızla eşleşen etiketlere sahip hedefleri sorgular.

bazel query 'attr(tags, "pizza", //src/main/java/com/example/customers/...)'

Bu sorgu, "customers" paketindeki "pizza" etiketine sahip tüm hedefleri döndürür.

Kendinizi test etme

Jale'nin ne sipariş etmek istediğini öğrenmek için bu sorguyu kullanın.

Yeni bağımlılık ekleme

Cafe Bazel, menüsünü genişletti. Müşteriler artık smoothie siparişi verebilir. Bu smoothie Strawberry ve Banana bileşenlerinden oluşuyor.

Öncelikle smoothie'nin bağlı olduğu malzemeleri ekleyin: Strawberry.java ve Banana.java. Boş Java sınıflarını ekleyin.

src/main/java/com/example/ingredients/Strawberry.java

package com.example.ingredients;

public class Strawberry {

}

src/main/java/com/example/ingredients/Banana.java

package com.example.ingredients;

public class Banana {

}

Ardından Smoothie.java dosyasını uygun dizine (dishes) ekleyin.

src/main/java/com/example/dishes/Smoothie.java

package com.example.dishes;

public class Smoothie {
    public static final String DISH_NAME = "Smoothie";
    public static final String DESCRIPTION = "Yummy and Refreshing";
}

Son olarak, bu dosyaları uygun BUILD dosyalarına kural olarak ekleyin. Her yeni bileşen için adı, herkese açık görünürlük ve yeni oluşturulan "src" dosyası da dahil olmak üzere yeni bir Java kitaplığı oluşturun. Güncellenen BUILD dosyasını aşağıdaki gibi göreceksiniz:

src/main/java/com/example/ingredients/BUILD

java_library(
    name = "cheese",
    visibility = ["//visibility:public"],
    srcs = ["Cheese.java"],
)

java_library(
    name = "dough",
    visibility = ["//visibility:public"],
    srcs = ["Dough.java"],
)

java_library(
    name = "macaroni",
    visibility = ["//visibility:public"],
    srcs = ["Macaroni.java"],
)

java_library(
    name = "tomato",
    visibility = ["//visibility:public"],
    srcs = ["Tomato.java"],
)

java_library(
    name = "strawberry",
    visibility = ["//visibility:public"],
    srcs = ["Strawberry.java"],
)

java_library(
    name = "banana",
    visibility = ["//visibility:public"],
    srcs = ["Banana.java"],
)

Yemeklerin bulunduğu BUILD dosyasında Smoothie için yeni bir kural eklemek istiyorsunuz. Bu işlem, "src" dosyası olarak Smoothie için oluşturulan Java dosyasını ve smoothie'nin her bir malzemesi için belirlediğiniz yeni kuralları içerir.

src/main/java/com/example/dishes/BUILD

java_library(
    name = "macAndCheese",
    visibility = ["//visibility:public"],
    srcs = ["MacAndCheese.java"],
    deps = [
        "//src/main/java/com/example/ingredients:cheese",
        "//src/main/java/com/example/ingredients:macaroni",
    ],
)

java_library(
    name = "pizza",
    visibility = ["//visibility:public"],
    srcs = ["Pizza.java"],
    deps = [
        "//src/main/java/com/example/ingredients:cheese",
        "//src/main/java/com/example/ingredients:dough",
        "//src/main/java/com/example/ingredients:tomato",
    ],
)

java_library(
    name = "smoothie",
    visibility = ["//visibility:public"],
    srcs = ["Smoothie.java"],
    deps = [
        "//src/main/java/com/example/ingredients:strawberry",
        "//src/main/java/com/example/ingredients:banana",
    ],
)

Son olarak, smoothie'yi şefin BUILD dosyasına bağımlılık olarak eklemeniz gerekir.

src/main/java/com/example/restaurant/BUILD

java\_library(
    name = "chef",
    visibility = ["//visibility:public"],
    srcs = [
        "Chef.java",
    ],

    deps = [
        "//src/main/java/com/example/dishes:macAndCheese",
        "//src/main/java/com/example/dishes:pizza",
        "//src/main/java/com/example/dishes:smoothie",
    ],
)

java\_library(
    name = "cafe",
    visibility = ["//visibility:public"],
    srcs = [
        "Cafe.java",
    ],
    deps = [
        ":chef",
    ],
)

Hata olmadığını onaylamak için cafe öğesini tekrar oluşturun. Derleme başarılı olursa tebrikler. "Cafe" için yeni bir bağımlılık eklediniz. Aksi takdirde yazım hatalarına ve paket adlarına dikkat edin. BUILD dosyası yazma hakkında daha fazla bilgi için BUILD Stil Kılavuzu'na bakın.

Şimdi, öncekiyle karşılaştırmak için Smoothie eklenmiş yeni bağımlılık grafiğini görselleştirin. Netlik için grafik girişini graph2.in ve graph2.png olarak adlandırın.

bazel query --noimplicit_deps 'deps(:runner)' --output graph > graph2.in

dot -Tpng < graph2.in > graph2.png

graph2.png öğesine baktığınızda Smoothie öğesinin diğer yemeklere olan ortak bağımlılığı olmadığını, ancak Chef için temel alınan bir başka hedef olduğunu görebilirsiniz.

somepath() ve allpaths()

Bir paketin neden başka bir pakete bağlı olduğunu sorgulamak isterseniz ne olur? İkisi arasındaki bağımlılık yolunu görüntüleyerek yanıtı bulabilirsiniz.

Bağımlılık yollarını bulmanıza yardımcı olabilecek iki işlev vardır: somepath() ve allpaths(). S başlangıç hedefi ve E bitiş noktası verildiğinde somepath(S,E) kullanarak S ile E arasında bir yol bulun.

"Şef" ve "Peynir" hedefleri arasındaki ilişkilere bakarak bu iki işlev arasındaki farkları keşfedin. Bir hedeften diğerine gidilebilecek farklı yollar vardır:

• Şef → MacAndCheese → Peynir
• Şef → Pizza → Peynir

somepath(), iki seçenekten tek bir yol sağlarken "allpaths()" her olası yolu döndürür.

Cafe Bazel'i örnek olarak kullanarak aşağıdakileri çalıştırın:

bazel query "somepath(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)"

//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef
//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/ingredients:cheese

Çıkış, Cafe → Şef → MacAndCheese → Peynir ilk yolunu izler. Bunun yerine allpaths() kullanırsanız:

bazel query "allpaths(//src/main/java/com/example/restaurant/..., //src/main/java/com/example/ingredients:cheese)"

//src/main/java/com/example/dishes:macAndCheese
//src/main/java/com/example/dishes:pizza
//src/main/java/com/example/ingredients:cheese
//src/main/java/com/example/restaurant:cafe
//src/main/java/com/example/restaurant:chef

Bağımlılıkların düzleştirilmiş bir listesi olduğu için allpaths() işlevinin çıktısının okunması biraz daha zordur. Graphviz'i kullanarak bu grafiği görselleştirmek, ilişkinin daha net anlaşılmasını sağlar.

Kendinizi test etme

Cafe Bazel'in müşterilerinden biri, restoranın ilk incelemesini yaptı. Maalesef yorumda, inceleyenin kimliği ve hangi yemeğe atıfta bulunduğu gibi bazı bilgiler eksik. Neyse ki, Bazel ile bu bilgilere erişebilirsiniz. reviews paketi, gizli müşteriden gelen bir yorumu yazdıran bir program içerir. Aşağıdakilerle derleyip çalıştırın:

bazel build //src/main/java/com/example/reviews:review

bazel-bin/src/main/java/com/example/reviews/review

Yalnızca Bazel sorgularını kullanarak yorumu kimin yazdığını ve hangi yemeği tarif ettiğini bulmaya çalışın.

Özet

Tebrikler! Artık kendi projelerinizde deneyebilirsiniz. Sorgu dili söz dizimi hakkında daha fazla bilgi edinmek için Sorgu referans sayfasına bakın. Daha gelişmiş sorgular mı istiyorsunuz? Sorgu kılavuzu, bu kılavuzda ele alınanlardan daha fazla kullanım alanının ayrıntılı bir listesini sunar.