SysML v2
holarch komut satırı aracı
holarch komut satırı aracı ve Holarch Language Engine ile derlemelerde ve CI'da SysML v2 modellerini denetleyin, biçimlendirin ve dışa aktarın; GitHub Actions ve diğer CI sistemleri, JSON ve SARIF raporları, çıkış kodları, API belirteci veya lisans dosyasıyla oturum açma.
Bu sayfada
- Genel bakış
- Kavramlar
- Nasıl kullanılır
- Ne zaman ve neden
- Kurulum
- Bir API belirteciyle oturum açma
- Bir modeli denetleme
- Dosyaları biçimlendirme
- Modeli SysML v2 JSON olarak dışa aktarma
- GitHub Actions'ta çalıştırma
- Diğer CI sistemlerinde çalıştırma
- Çalışılmış örnek: Hybrid Car demosu
- İpuçları ve iyi uygulamalar
- Yaygın hatalar
- Diğer özelliklerle nasıl bağlantılıdır
- Komutlar
- Araç için oturum açma
- Raporlar
- Çıkış kodları
- İletiler
- Sınırlar
- İlgili sayfalar
Genel bakış
holarch, SysML v2 metin dosyalarını Holarch düzenleyicisinin kullandığı motorla, yani Holarch Language Engine ile denetleyen bir komut satırı aracıdır. Onu kendi bilgisayarınızda veya bir derlemede çalıştırın: bir klasördeki her .sysml dosyasını okur, sorunları dosya, satır ve sütunla bildirir ve modelde hata olduğunda sıfırdan farklı bir kodla çıkar; böylece modeli bozuk bir pull request denetimlerden geçemez.
Araç üç şey yapar:
- Denetleme: modelin tüm dosyalarında sözdizimi, adlar, türler, özelleştirmeler, çokluklar, birimler ve motorun diğer kuralları. Metin, JSON, SARIF (kod taraması için) veya GitHub ek açıklamaları olarak raporlar.
- Biçimlendirme: dosyaları her yorumu koruyarak tek bir standart yerleşimde (dört boşluklu girinti, satır başına bir öğe, standart aralıklar) yeniden yazar.
- Dışa aktarma: modeli Systems Modeling API'nin değişim biçimi olan SysML v2 JSON olarak yazar.
Araç Individual ve Team planlarıyla (deneme dahil), bir Holarch Language Engine lisansıyla ve bir self-hosted sürüm lisansıyla gelir. Bir Holarch projesi gerektirmez: deponuzdaki dosyalar üzerinde çalışır.
Kavramlar
- Model: belirttiğiniz klasörlerin (varsayılan: geçerli klasör) altındaki tüm
.sysmldosyaları, tek bir model olarak okunur. Bir dosyada bildirilen ad, bir Holarch projesindeki paketlerde olduğu gibi diğer dosyalarda çözümlenir. Adı nokta ile başlayan klasörler (örneğin.git) atlanır. - KerML dosyaları:
.kermldosyaları, KerML okuyan motor sürümleri tarafından KerML olarak denetlenir. Eski motor sürümleri bunları atlanmış olarak listeler; bu bir hata değildir. - Tanılamalar: her sorunun bir kodu (örneğin
name.unresolved), bir önem düzeyi (hata, uyarı veya not), bir konumu ve Holarch düzenleyicisindekiyle aynı sözcüklerle bir iletisi vardır.--warnings-as-errorseklemediğiniz sürece yalnızca hatalar bir denetimi başarısız kılar. - Oturum açma: araç günde bir kez API belirtecinizin bir Individual veya Team planına ait olduğunu denetler ya da hiçbir ağ erişimi olmadan bir lisans dosyasını okur. Bkz. Araç için oturum açma.
- Motor: araç, derlenmiş Holarch Language Engine'i ve SysML v2 standart kitaplığını içerir.
holarch versionbunların sürümlerini ve motorun telif hakkı bildirimini yazdırır.
Nasıl kullanılır
Ne zaman ve neden
Aracı, SysML v2 metninin bir kaynak deposunda bulunduğu yerlerde kullanın: tasarımcılar .sysml dosyalarını seçtikleri düzenleyicide düzenler ve her değişiklik birleştirilmeden önce denetlenir. Bir derleyicinin kod için yaptığı gibi her commit'te “bu model hâlâ tutarlı mı?” sorusunu yanıtlar. Modelleme, diyagramlar ve incelemeler için Holarch düzenleyicisini; düzenlemeler arasında dosyaları korumak için aracı kullanın. Bir modeli depo ile bir Holarch projesi arasında taşımak için İçe ve dışa aktarma kullanın.
Kurulum
- Python 3.9 veya sonrasını kurun.
- Aracı sisteminiz için (Linux x86-64, Linux arm64 veya Apple silikonlu macOS) pip ile kurun:
python3 -m pip install holarch-cli
- Kurulumu denetleyin:
holarch versionaraç, motor ve kitaplık sürümlerini yazdırır.
Bir API belirteciyle oturum açma
- Holarch'ta Hesap ayarları → API belirteçleri sayfasını açın ve bir belirteç oluşturun. Salt okunur erişim yeterlidir.
- Belirteci
HOLARCH_API_KEYortam değişkenine koyun (CI'da: bir gizli değer). holarch whoamiçalıştırın. Planınızı ve hesabınızı yazdırır, örneğin"plan": "team".
Bir modeli denetleme
holarch check models/
Her sorun bir satırdır, ardından bir özet gelir:
models/requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here. Check the spelling, or import its package.
6 files checked: 1 error, 0 warnings.
Modelde hata olduğunda çıkış kodu 1, aksi takdirde 0'dır. Uyarılarda da başarısız olmak için --warnings-as-errors ekleyin.
Dosyaları biçimlendirme
holarch format models/çalıştırın. Değişen her dosya “reformatted <file>” olarak listelenir.- CI'da dosyaları değiştirmeden yerleşimi denetlemek için
holarch format --check models/çalıştırın. “would reformat <file>” listeler ve bir dosya değişecekse 1 ile çıkar. - Değişiklikleri önce görmek için
holarch format --diff models/çalıştırın.
Sözdizimi hataları olan bir dosya biçimlendirilmez (“not formatted: the file has syntax errors.”). Yorumlar oldukları yerde kalır: bir öğeden önceki notlar onun üstünde, satır sonundaki bir not o satırın sonunda kalır.
Modeli SysML v2 JSON olarak dışa aktarma
holarch export models/ -o model.json
Dosya, Systems Modeling API'nin standart öğe dizisini tutar. Aynı dosyalar her zaman aynı JSON'u verir; bu nedenle dışa aktarma commit edilip karşılaştırılabilir. Hataları olan bir model dışa aktarılmaz (“The model has errors, so it was not exported.”); yine de dışa aktarmak için --force ekleyin. Bir Holarch projesine birebir içe aktarma için yalnızca Holarch'ın okuduklarını (öğe sırası, yazım) korumak üzere --holarch-fields ekleyin.
GitHub Actions'ta çalıştırma
- API belirtecini
HOLARCH_API_KEYadlı bir depo gizli değeri olarak ekleyin (Settings → Secrets and variables → Actions). - Bir iş akışı dosyası ekleyin, örneğin
.github/workflows/sysml.yml:
name: SysML model
on: [push, pull_request]
jobs:
check:
runs-on: ubuntu-latest
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.12"
- run: python -m pip install holarch-cli
- run: holarch check models --format github --sarif holarch.sarif
env:
HOLARCH_API_KEY: ${{ secrets.HOLARCH_API_KEY }}
- run: holarch format --check models
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: holarch.sarif
- Gönderin (push). Sorunlar pull request'in değişen satırlarında ek açıklama olarak görünür ve modelde hata olduğunda veya bir dosya standart yerleşimde olmadığında iş başarısız olur. Yalnızca modeli denetlemek için
holarch format --checkadımını çıkarın.
Son adım SARIF raporunu kod taramasına yükler; sorunlar orada Security → Code scanning altında listelenir. Deponuz kod taraması kullanmıyorsa bu adımı çıkarın: ek açıklamalar onsuz da çalışır.
Diğer CI sistemlerinde çalıştırma
Python 3.9 veya sonrasına sahip her CI sistemi aynı komutları çalıştırır. Aracı kurun, belirteci bir gizli değerden ayarlayın, denetleyin:
python3 -m pip install holarch-cli
holarch check models/ --sarif holarch.sarif --json holarch.json
Örneğin GitLab CI (.gitlab-ci.yml, maskelenmiş bir CI/CD değişkeni olarak HOLARCH_API_KEY ile):
sysml:
image: python:3.12
script:
- pip install holarch-cli
- holarch check models/ --sarif gl-holarch.sarif
- holarch format --check models/
artifacts:
when: always
paths: [gl-holarch.sarif]
Jenkins, Azure Pipelines, CircleCI ve diğerleri aynı şekilde çalışır: bir adım aracı kurar, sonraki holarch check çalıştırır; sıfırdan farklı bir çıkış kodu derlemeyi başarısız kılar. Sayıları bir panoda görmek istediğinizde JSON raporunu (--json) bir derleme yapıtı olarak saklayın.
Çalışılmış örnek: Hybrid Car demosu
- Demoyu oluşturun: Projeleri yönet sayfasında Proje dosyaları ▾ → Yeni demo proje → Hybrid Car (SysML v2) seçeneğine tıklayın.
- Model → İçe ve dışa aktarma sayfasını açın. Dışa aktar altında Tüm model ve SysML v2 metni seçeneklerini seçin, Dışa aktar düğmesine tıklayın ve indirilen dosyayı deponuzdaki
modelsklasörüne açın. holarch check modelsçalıştırın. Sonuç “6 files checked: 0 errors, 0 warnings.” olur.requirements.sysmliçindeattribute maxCurbMass : MassValueifadesiniMassValuolarak değiştirin ve denetimi yeniden çalıştırın.requirements.sysml:14:27: error name.unresolved: “MassValu” is not defined here.bildirir ve 1 ile çıkar.- Değişikliği geri alın.
holarch format modelskomutunu bir kez çalıştırın ve dosyaları commit edin; böylece sonrakiformat --checkçalıştırmaları geçer. - Yukarıdaki GitHub iş akışını ekleyin. Modeli bozan sonraki her pull request denetiminden geçemez.
İpuçları ve iyi uygulamalar
- Her dosyanın içeriğini bir pakette tutun. Herhangi bir paketin dışındaki öğeler çalışır, ancak dosya başına bir paket adları dosyalar arasında benzersiz tutar.
- CI için hiçbir projeyle sınırlı olmayan salt okunur bir belirteç kullanın: aracın proje erişimine ihtiyacı yoktur.
format-checközelliğini açmadan önce bir kez biçimlendirip sonucu commit edin; aksi takdirde ilk çalıştırma her dosyada başarısız olur.- Yeni bir motor sürümünün bir incelemenin ortasında sonuçları değiştirmemesi için CI'da aracın sürümünü sabitleyin (
holarch-cli==<version>). - İnternet erişimi olmayan çalıştırıcılar belirteç yerine bir lisans dosyası kullanır.
Yaygın hatalar
- “No .sysml or .kerml files found”: yol yanlış veya dosyalar adı nokta ile başlayan bir klasörde.
- Adlar yalnızca bir dosyada çözümlenmiyor: dosya, başka bir dosyanın kullandığı adları bildiriyor ve o diğer dosyada bir sözdizimi hatası var. Önce sözdizimi hatasını düzeltin; rapor hangi dosyaların dışarıda bırakıldığını belirtir.
- İş 3 çıkış koduyla başarısız oluyor: belirteç eksik, yanlış veya Free planındaki bir hesaba ait. İleti hangisi olduğunu belirtir.
Diğer özelliklerle nasıl bağlantılıdır
- Denetimler, Holarch düzenleyicisinin SysML v2 metni ve SysML v2 projeleri için Model denetimleri denetimleriyle aynıdır, aynı iletilerle (SysML v2 metin düzenleyicisi).
- Bir projeden dışa aktarılan dosyalar (İçe ve dışa aktarma) sorunsuz denetlenir; aracın dışa aktardığı JSON bir projeye içe aktarılır.
- Dosyalar yerine Holarch'ta incelemeden geçmesi gereken değişiklikler için değişiklikleri öneri olarak gelen API'yi veya Python istemcisi'ni kullanın.
Komutlar
| Komut | Ne yapar |
|---|---|
holarch check [paths] | Modeli denetler; sorunları bildirir; hatalarda 1 ile çıkar |
holarch format [paths] | Dosyaları standart yerleşimde yeniden yazar |
holarch export [paths] | Modeli SysML v2 JSON olarak yazar |
holarch whoami | Belirtecin veya lisans dosyasının neye izin verdiğini gösterir |
holarch version | Araç, motor ve kitaplık sürümlerini ve motorun telif hakkı bildirimini yazdırır (oturum açma gerekmez) |
Yollar dosya veya klasördür; varsayılan geçerli klasördür. Klasörler alt klasörleriyle birlikte aranır.
check seçenekleri
| Seçenek | Anlamı |
|---|---|
--format human|json|sarif|github | Standart çıktıdaki rapor (varsayılan human) |
--output FILE | Bunun yerine o raporu bir dosyaya yazar |
--sarif FILE | Ayrıca bir SARIF 2.1.0 raporu yazar |
--json FILE | Ayrıca bir JSON raporu yazar |
--warnings-as-errors | Uyarılarda da 1 ile çıkar |
format seçenekleri
| Seçenek | Anlamı |
|---|---|
--check | Hiçbir şeyi değiştirmez; bir dosya değişecekse 1 ile çıkar |
--diff | Hiçbir şeyi değiştirmez; değişiklikleri birleşik fark olarak yazdırır |
--stdout | Bir dosyanın biçimlendirilmiş metnini yazmak yerine yazdırır |
export seçenekleri
| Seçenek | Anlamı |
|---|---|
-o FILE, --output FILE | Bir dosyaya yazar (varsayılan: standart çıktı) |
--holarch-fields | Birebir gidiş dönüş için yalnızca Holarch'ın okuduğu alanları ekler |
--force | Hataları olan bir modeli dışa aktarır (sözdizimi hataları olanı asla) |
Oturum açan her komutun seçenekleri
| Seçenek | Ortam değişkeni | Anlamı |
|---|---|---|
--api-key KEY | HOLARCH_API_KEY | Bir API belirteci (hol_…); belirteç günlüklerin dışında kalsın diye değişkeni tercih edin |
--license FILE | HOLARCH_LICENSE_FILE | Çevrimdışı kullanım için bir lisans dosyası |
--server URL | HOLARCH_SERVER | Belirteci denetleyen Holarch sunucusu (bir https adresi) |
--timeout SECONDS | Her motor adımı için süre sınırı (varsayılan 60) |
Araç için oturum açma
Araç, bunlardan biri mevcut olduğunda çalışır:
- Individual veya Team planına ait bir API belirteci; Individual denemesi dahil. Araç sunucuya bir kez sorar ve yanıtı bir gün boyunca bir önbellek dosyasında tutar (
~/.cache/holarch/entitlement.json;HOLARCH_CACHE_DIRkonumunu değiştirir). Önbellek planı ve hesap e-postasını tutar, belirteci asla tutmaz. Sunucuya ulaşılamadığında en fazla 7 günlük bir yanıt, bir notla birlikte yine geçerli sayılır. - Bir lisans dosyası; Holarch Language Engine lisans sahipleri, self-hosted sürüm müşterileri ve internet erişimi olmayan çalıştırıcılar için. Araç dosyanın imzasını kendisi denetler ve hiçbir zaman bir sunucuya bağlanmaz. Her geçerli lisans aracı ek ücret olmadan içerir:
- Holarch Language Engine lisansı: motor tesliminizdeki lisans anahtarını (
l1.ile başlayan metin) bir dosyaya kaydedin, örneğinholarch-engine.key, ve--licenseveyaHOLARCH_LICENSE_FILEile onu gösterin. Bir e-postanın eklediği satır sonları önemli değildir. Anahtarın lisanslı web adresleri ve sunucu kullanımı aracı değil, ürününüzdeki motoru kapsar. Anahtarın bitiş tarihinden sonraki 14 gün içinde araç çalışmaya devam eder ve bir hatırlatma yazdırır. - Self-hosted sürüm lisansı: Holarch sunucunuzun lisans dosyasını olduğu gibi kullanın. Son 30 gününde araç bir hatırlatma yazdırır. Bitiş tarihinden sonraki 30 gün içinde (lisansın ek süresi) araç çalışmaya devam eder ve kalan günleri yazdırır; bundan sonra yenilenmiş bir lisans kurulana kadar durur.
- Holarch Language Engine lisansı: motor tesliminizdeki lisans anahtarını (
14 gününü aşmış bir motor anahtarı da yenilenmiş bir anahtar kurulana kadar aracı durdurur.
Free planındaki bir hesabın belirteci reddedilir; hesap API'yi akademik bir e-posta adresi aracılığıyla korusa da. Individual denemesi aracı içerir.
CI'da lisans dosyaları
Lisansı depoda değil, bir gizli değer olarak saklayın. CI'da gizli değeri checkout dışındaki bir dosyaya yazın (GitHub Actions'ta $RUNNER_TEMP altına) ve HOLARCH_LICENSE_FILE değişkenini onun yoluna ayarlayın.
Raporlar
JSON çıktısı
--format json ve --json FILE şunları yazar:
| Alan | Anlamı |
|---|---|
tool, version, engine | holarch, aracın sürümü, motorun sürümü |
files | Aracın çalıştığı klasöre göre göreli yollar olarak denetlenen dosyalar |
summary | errors, warnings, notes, files |
diagnostics | file, line, column, endLine, endColumn (1 tabanlı), severity (error, warning, info), code, message, args |
skipped | Denetlenmeyen dosyalar, nedeniyle birlikte (eski bir motorla KerML dosyaları) |
excluded | Dosyalar arası denetimlerin dışında bırakılan, sözdizimi hataları olan dosyalar |
Sütunlar Unicode karakterlerini (kod noktalarını) sayar.
SARIF
--format sarif ve --sarif FILE, her tanılama kodu için bir kural, error, warning veya note olarak önem düzeyi ve aracın çalıştığı klasöre göre göreli yollarla SARIF 2.1.0 yazar. Kod taramasının dosyaları bulması için aracı deponun kökünde çalıştırın.
GitHub ek açıklamaları
--format github, her sorun için GitHub Actions'ın ek açıklama olarak gösterdiği bir iş akışı komutu (::error file=…,line=…,col=…::message), ardından özet satırını yazdırır.
Çıkış kodları
| Kod | Anlamı |
|---|---|
| 0 | Hata yok (format: değiştirilecek bir şey kalmadı) |
| 1 | Modelde hatalar var; format --check veya --diff: bir dosya değişecek veya bir dosya biçimlendirilemedi; export: hatalar nedeniyle reddedildi |
| 2 | Yanlış kullanım: bilinmeyen bir seçenek, var olmayan bir yol, model dosyası yok |
| 3 | Oturum açılmamış veya yetki yok: belirteç veya lisans dosyası yok, reddedilmiş bir belirteç, bir Free planı, geçersiz, değiştirilmiş veya süresi dolmuş bir lisans dosyası |
| 4 | Motor çalışamıyor veya modeli denetlenemeyecek kadar büyük ya da yavaş olduğu için reddetti |
İletiler
| İleti | Anlamı |
|---|---|
| “The holarch command line tool needs a Holarch API token of an Individual or Team plan (HOLARCH_API_KEY, or --api-key) or a Holarch Language Engine license file (HOLARCH_LICENSE_FILE, or --license).” (holarch komut satırı aracı, bir Individual veya Team planına ait bir Holarch API belirteci ya da bir Holarch Language Engine lisans dosyası gerektirir.) | Ne belirteç ne de lisans dosyası ayarlanmış |
| “The holarch command line tool comes with the Individual and Team plans. Choose a plan in Account Settings → Plan & Billing, or use a Holarch Language Engine license file.” (Araç Individual ve Team planlarıyla gelir; Hesap ayarları → Plan ve faturalandırma içinde bir plan seçin veya bir lisans dosyası kullanın.) | Belirtecin hesabı Free planında |
| “The API and MCP come with the Individual and Team plans.” (API ve MCP, Individual ve Team planlarıyla gelir.) | Belirtecin hesabı Free planında ve API erişimi de yok |
| “The API token is not valid: it is wrong, revoked or expired, or its account cannot sign in.” (API belirteci geçersiz: yanlış, iptal edilmiş veya süresi dolmuş ya da hesabı oturum açamıyor.) | Yeni bir belirteç oluşturun |
| “The license file's signature does not verify. Use the file exactly as it was delivered.” (Lisans dosyasının imzası doğrulanmıyor; dosyayı teslim edildiği gibi kullanın.) | Lisans dosyası değiştirilmiş veya hasarlı |
| “License <id> expired on <date>. Install a renewed license file.” (Lisansın süresi doldu; yenilenmiş bir lisans dosyası kurun.) | Bir self-hosted lisansı 30 günden uzun süre önce veya bir motor lisans anahtarı 14 günden uzun süre önce sona erdi |
| “The engine license key's signature does not verify. Use the key exactly as it was delivered.” (Motor lisans anahtarının imzası doğrulanmıyor; anahtarı teslim edildiği gibi kullanın.) | Dosyadaki anahtar değiştirilmiş veya başka bir ürüne ait |
| “The engine license key is not complete. Copy the whole key (l1.….…) into the file.” (Motor lisans anahtarı eksik; anahtarın tamamını dosyaya kopyalayın.) | Anahtarın bir kısmı eksik |
| “… cannot be reached to check the API token” (API belirtecini denetlemek için … adresine ulaşılamıyor) | Bağlantı yok ve önbellekte yakın tarihli bir yanıt yok; yeniden deneyin veya bir lisans dosyası kullanın |
| “<file>: not formatted: the file has syntax errors.” (dosya biçimlendirilmedi: sözdizimi hataları var.) | Bunları görmek için holarch check çalıştırın |
| “<file>: not formatted: a comment could not be kept in place.” (dosya biçimlendirilmedi: bir yorum yerinde tutulamadı.) | Dosya değişmeden kalır; araç hiçbir zaman bir yorumu atmaz |
| “The model has errors, so it was not exported.” (Modelde hatalar olduğu için dışa aktarılmadı.) | Hataları düzeltin veya --force ekleyin |
| “The installed engine does not carry the Holarch Language Engine copyright notice, so it is not a genuine Holarch build.” (Kurulu motor Holarch Language Engine telif hakkı bildirimini taşımıyor; bu nedenle gerçek bir Holarch derlemesi değil.) | Aracı yeniden kurun |
Sınırlar
- Düzenleyicide olduğu gibi bir modelde dil başına en fazla 8 MB SysML metni ve en fazla 64 KB'lık satırlar.
- Tek bir çalıştırmada en fazla 10,000 dosya.
- Her motor adımı
--timeoutsaniye sonra durur (varsayılan 60). - Adlar aynı dildeki dosyalar arasında çözümlenir: bir
.sysmldosyası bir.kermldosyasında bildirilen adları görmez.