CMake stil kılavuzu

Makale
01/10/2024

Aşağıdakilerden biri olan tüm CMake betiklerini bekliyoruz:

dizininde scripts/ veya
vcpkg-* Bağlantı noktasında

bu belgede belirtilen yönergeleri izlemelidir. Mevcut betikler henüz bu yönergeleri izlemeyebilir; eski betikleri bu yönergelere uygun olacak şekilde güncelleştirmeye devam edeceğiz.

Bu yönergeler betiklerimizde kararlılık oluşturmaya yöneliktir. Hem ileri hem de geri uyumluluğunu kolaylaştıracaklarını umuyoruz.

Yönergeler

Out-parameters dışında, işlev parametreleri yerine veya öğesine başvurmak ${ARG<N>}yerine her zaman kullanırızcmake_parse_arguments().
- "Betik yerel yardımcı işlevleri" için bunun izlenmesi gerekmez
  - Bu durumda, konumsal parametreler işlev bildirimine (kullanmak ${ARG<N>}yerine) yerleştirilmeli ve yerel kurallara (örn. snake_case) göre adlandırılmalıdır.
  - Özel durum: İsteğe bağlı olan konumsal parametrelere denetlendikten sonra ARGCaracılığıyla set(argument_name "${ARG<N>}")bir ad verilmelidir.
- Out-parameters işlevin ilk parametresi olmalıdır. Örnek:
```
function(format out_var)
  cmake_parse_arguments(PARSE_ARGV 1 "arg" ...)
  # ... set(buffer "output")
  set("${out_var}" "${buffer}" PARENT_SCOPE)
endfunction()
```
Ayrıştırılmamış veya kullanılmayan bağımsız değişken yoktur. Her zaman veya arg_UNPARSED_ARGUMENTSöğesini ARGN denetleyin. FATAL_ERROR mümkün olduğunda, WARNING geriye dönük uyumluluk için gerekirse.
Tümü cmake_parse_arguments kullanmalıdır PARSE_ARGV.
Tüm foreach döngüler , veya IN ITEMSRANGEkullanmalıdırIN LISTS.
ve ${ARGN} değişkenleri${ARGV}, kullanıcıya yararlı iletiler dışında başvurulmaz.
- (örn. message(FATAL_ERROR "blah was passed extra arguments: ${ARGN}"))
Makroları veya en üst düzey kodu değil her zaman işlevleri kullanırız.
- Özel durum: "betik yerel yardımcı makroları". Bazen küçük bir makro tanımlamak yararlı olabilir. Bu işlem tedbirli bir şekilde yapılmalı ve işlevler tercih edilmelidir.
- Özel durum: vcpkg.cmake's find_package.
Betik ağacındaki betiklerin normal işlemin bir parçası olarak gözlemlenebilir değişikliklere ihtiyacı olması beklenmemelidir.
- Örnek ihlal: vcpkg_acquire_msys() MSYS projesinin eski paketleri bırakması nedeniyle zaman içinde güncelleştirilmesi gereken sabit kodlanmış paketlere ve sürümlere sahiptir.
- Örnek özel durum: vcpkg_from_sourceforge() bakıma ihtiyacı olan ancak arayanlar üzerinde gözlemlenebilir bir davranış etkisi olmayan yansıtmaların bir listesine sahiptir.
Alıntılama kuralları: CMake'te üç tür bağımsız değişken vardır: alıntısız (foo(BAR)), tırnak işareti (foo("BAR")) ve köşeli ayraçlı (foo([[BAR]])). Doğru alıntı yapmak için şu kuralları izleyin:
- Bağımsız değişken bir genişletme ${...}içeriyorsa, tırnak içine alınmalıdır.
  - Özel durum: bir değişken birden çok bağımsız değişken olarak işleve geçirildiğinde bir "splat" değişken genişletmesi. Bu durumda, bağımsız değişken basitçe olmalıdır ${foo}:
```
vcpkg_list(SET working_directory)
if(DEFINED "arg_WORKING_DIRECTORY")
  vcpkg_list(SET working_directory WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")
endif()
# calls do_the_thing() if NOT DEFINED arg_WORKING_DIRECTORY,
# else calls do_the_thing(WORKING_DIRECTORY "${arg_WORKING_DIRECTORY}")
do_the_thing(${working_directory})
```
- Aksi takdirde, bağımsız değişken , \"veya \$olmayan \\kaçış dizileri içeriyorsa, bu bağımsız değişken tırnak içine alınmış bir bağımsız değişken olmalıdır.
  - Örneğin: "foo\nbar" tırnak içine alınmalıdır.
- Aksi takdirde, bağımsız değişken bir \, "veya $içeriyorsa, bu bağımsız değişken köşeli ayraç içine alınmalıdır.
  - Örnek:
```
set(x [[foo\bar]])
set(y [=[foo([[bar\baz]])]=])
```
- Aksi takdirde, bağımsız değişken alfasayısal veya _olmayan karakterler içeriyorsa, bu bağımsız değişken tırnak içine alınmalıdır.
- Aksi takdirde bağımsız değişkenin tırnak işareti kaldırılmalıdır.
- Özel durum: türünde <variable|string> bağımsız değişkenler if() her zaman tırnak içine alınmalıdır:
  - Karşılaştırma işleçlerinin her iki bağımsız değişkeni de - EQUAL, STREQUAL, VERSION_LESSvb.
  - ve için ilk bağımsız değişken MATCHESIN_LIST
  - Örnek:
```
if("${FOO}" STREQUAL "BAR") # ...
if("${BAZ}" EQUAL "0") # ...
if("FOO" IN_LIST list_variable) # ...
if("${bar}" MATCHES [[a[bcd]+\.[bcd]+]]) # ...
```
  - Tek ifadeler ve almayan <variable|string>diğer koşul türleri için normal kuralları kullanın.
Basit out-parameters dışında hiçbir "işaretçi" veya "in-out" parametresi yoktur (burada bir kullanıcı içerik yerine değişken adı geçirir).
Değişkenlerin boş olduğu varsayılmaz. Değişkenin yerel olarak kullanılması amaçlanıyorsa, bir dize değişkeniyse ve vcpkg_list(SET foo) bir liste değişkeniyse ile birlikte açıkça boş set(foo "") olarak başlatılmalıdır.
set(var) kullanılmamalıdır. Bir değişkeni ayarlamak, set(var "") boş dizeye ayarlamak ve vcpkg_list(SET var) boş listeye ayarlamak için kullanınunset(var). Not: boş dize ve boş liste aynı değerdir;bu, sonuç farkı yerine bir notasyon farkıdır
Bir API sınırı boyunca üst kapsamdan devralınması beklenen tüm değişkenler (dosya yerel işlevi değil) belgelenmelidir. Üçlü dosyalarda belirtilen tüm değişkenler belgelenmiş olarak kabul edilir.
Out parametreleri yalnızca içinde PARENT_SCOPE ayarlanır ve hiçbir zaman okunmaz. Ayrıca bir işlev kapsamı aracılığıyla parametreleri iletmek için yardımcıya z_vcpkg_forward_output_variable() bakın.
CACHE değişkenler yalnızca güçlü bir şekilde bağlanmış işlevler arasında dahili olarak paylaşılan genel değişkenler için ve yineleme işini önlemek için tek bir işlev içindeki iç durum için kullanılır. Bunlar son derece dikkatli kullanılmalıdır ve diğer kodlar tarafından tanımlanacak yerel değişkenlerle çakışmayı önlemek için ön ekini kullanmalıdır Z_VCPKG_ .
- Örnekler:
  - vcpkg_cmake_configure's Z_VCPKG_CMAKE_GENERATOR
  - z_vcpkg_get_cmake_vars's Z_VCPKG_GET_CMAKE_VARS_FILE
include()s yalnızca veya vcpkg-port-config.cmakeiçinde ports.cmake izin verilir.
foreach(RANGE)'nin bağımsız değişkenleri her zaman doğal sayılar olmalı ve <start>her zaman değerinden küçük veya eşit <stop>olmalıdır.
- Bu, aşağıdaki gibi bir şey tarafından denetlenmelidir:
```
if("${start}" LESS_EQUAL "${end}")
  foreach(RANGE "${start}" "${end}")
    ...
  endforeach()
endif()
```
Tüm bağlantı noktası tabanlı betikler, birden çok kez dahil edilmemek için kullanılmalıdır include_guard(GLOBAL) .

Gerektirecek CMake sürümleri

dışında vcpkg.cmaketüm CMake betikleri, içinde bulunan cmake_minimum_requiredports.cmakeCMake sürümünü varsayabilir.
- CMake'in cmake_minimum_required yeni bir sürümü her eklendiğindevcpkgTools.xml, tüm yardımcı CMakeLists.txt dosyalarda olduğu gibi cmake_minimum_required bu da çarpılmalıdır.
vcpkg.cmake CMake sürümünün genel olarak 3.7.2 sürümüne geri döndüğünü varsaymalıdır
- Belirli işlevler ve seçenekler daha büyük bir CMake sürümü varsayabilir; varsa, bu işlevi veya seçeneği gerekli CMake sürümüyle açıklama satırı yaptığınızdan emin olun.

Mevcut işlevleri değiştirme

İç olmayan işlevlerdeki bağımsız değişkenleri hiçbir zaman kaldırmaz; Artık bir şey yapmamaları gerekiyorsa, bunları normal kabul edin ve kullanım konusunda uyarın.
Hiçbir zaman yeni bir zorunlu bağımsız değişken eklemeyin.

Değişkenleri adlandırma

cmake_parse_arguments: ön eki olarak ayarla "arg"
Yerel değişkenler ile adlandırılır snake_case
İç genel değişken adları ön ek olarak Z_VCPKG_eklenir.
Dış deneysel genel değişken adları ile X_VCPKG_ön eklenmiştir.
İç işlevler ön ekli z_vcpkg_
- Tek bir işlevin (yani yardımcı işlevlerin) iç işlevleri olarak adlandırılır [z_]<func>_<name>; burada <func> yardımcı oldukları işlevin adı ve <name> yardımcı işlevin yaptığı addır.
  - z_ , yoksa <func>z_, ancak yardımcı işlevine z_z_foo_barad vermediyseniz öne eklenmelidir.
Genel genel değişkenler olarak adlandırılır VCPKG_.

Aracılığıyla paylaş

CMake stil kılavuzu

Yönergeler

Gerektirecek CMake sürümleri

Mevcut işlevleri değiştirme

Değişkenleri adlandırma

Geri Bildirim

Ek kaynaklar