Sorun giderme

Bu şablonun kendi betiklerinin gerçekten karşılaştığı hata mesajları ve tam düzeltmeleri. Hatanız burada yoksa betiğin yazdırdığı [ERROR] ... satırını okuyun - 6-build-and-test-*, 7-build-all-* ve 10-release-* içindeki her başarısızlık noktası "bir şeyler ters gitti" demek yerine somut bir düzeltme yazdırır.

Hata mesajı (ya da belirti)	Neden	Düzeltme
'7-build-all-windows.bat' is not recognized as an internal or external command (bir betiği başka bir betikten, ya da başındaki .\/\ olmadan bir kabuktan çağırırken)	Bazı makinelerde NoDefaultCurrentDirectoryInExePath=1 ayarlıdır; bu hem cmd.exe'nin hem de PowerShell'in çıplak bir dosya adı için geçerli klasörü aramasını durdurur.	Bir betiği her zaman açık bir yolla çağırın: PowerShell'de .\7-build-all-windows.bat, başka bir .bat'in İÇİNDEN "%~dp07-build-all-windows.bat" (10-release-windows.bat'in 7-build-all-windows.bat'i çağırmak için yaptığı tam olarak budur).
tar'dan *.jar: Cannot stat: No such file or directory	cmd.exe *.jar'ı genişletmez; tar gerçek dosya adı yerine '*.jar' dizesini alır.	Dosyayı açıkça adlandırın (tar ... -C calculator-app\target calculator-app-1.1.0.jar). assemble.py her şeyi Python ile paketler, betikler bu hataya düşmez; yalnızca kendi tar komutlarınızda karşılaşırsınız.
rd /S /Q'nun yazdırdığı The system cannot find the file specified.	Henüz var olmayan bir klasörde (örn. hiçbir rapor üretilmeden önceki ilk çalıştırma) rd, sessizce hiçbir şey yapmak yerine hata verir.	Koruyun: if exist "klasör" rd /S /Q "klasör". Linux'ta rm -rf'de böyle bir sorun yoktur - eksik bir yol sessiz bir no-op'tur.
genhtml: ERROR: no valid records found in tracefile ...\lcov.info ve dosya 0 bayt	coverxygen'e giden --prefix argümanı "...\calculator-app\" olarak, yani kapanış çift tırnağının hemen ÖNÜNDE bir ters eğik çizgi ile tırnaklanmıştı. Windows'un argüman ayrıştırıcısı \"'yi kapanış tırnağı değil, kaçışlanmış (escaped) bir tırnak karakteri olarak görür, bu yüzden ondan sonraki her argümanı sessizce yutar ve coverxygen kaynak dizini olmadan çalışıp boş bir dosya üretir.	Tırnaklanmış bir Windows komut satırı argümanını asla ters eğik çizgiyle bitirmeyin. Bunun yerine ileri eğik çizgi kullanın ("...\calculator-app/" sorunsuzdur), ya da önce ters eğik çizgileri ileri eğik çizgiye çevirmek için %VAR:\=/% kullanın (7-build-all-windows.bat'in yaptığı budur), ya da argümanda boşluk yoksa hiç tırnaklamayın.
Can't open perl script "genhtml": No such file or directory	Chocolatey lcov kurulumundan gelen genhtml'in .exe uzantısı yoktur - bir Perl betiğidir. cmd.exe'nin where genhtml'i bir şey bulduğunu bildirir, ama çıplak genhtml kelimesini çalıştırmak işe yaramaz; gerçek yolu çözüp perl "<yol>"'u açıkça çalıştırmanız gerekir.	7-build-all-windows.bat, where genhtml'den çözülen yolu yakalar ve perl "<o yol>" ...'u açıkça çağırır. Linux'ta genhtml normal, doğrudan çalıştırılabilir bir komuttur - Perl sarmalayıcı gerekmez.
Dokümantasyon-kapsama raporu sessizce boş; coverxygen hiçbir şey üretmiyor ve açıkça yanlış bir şey yazdırmıyor	PATH'teki düz python, coverxygen paketine sahip olmayan alakasız bir kuruluma (örn. bir grafik uygulamasının gömülü Python 2.7'si) çözülmüştü, bu yüzden python -m coverxygen modülü bulamadı ve betik bunu kontrol etmiyordu.	Belirli, bilinen-iyi bir yorumlayıcıyı çağırın: py -3.12 -m coverxygen ... (py başlatıcısı, python'ın neye işaret ettiğinden bağımsız olarak istediğiniz kesin sürümü seçer). 7-build-all-windows.bat önce py -3.12 -c "import coverxygen"'i kontrol eder ve eksikse sessizce hiçbir şey üretmek yerine somut bir hata yazdırır.
where python beklemediğiniz bir Python gösteriyor (Inkscape, GIMP, eski bir 2.7, ...)	Birçok geliştirme-dışı uygulama kendi gömülü Python'unu getirir ve genellikle gerçek kurulumunuzun önünde PATH'e ekler.	Betiklerinizde ya da kendi araçlarınızda çıplak python/pip'e güvenmeyin. Belirsizliğe yer bırakmayan py -3.12'yi (Python Launcher for Windows) kullanın, ya da where python'ı kontrol edip çıplak python'ın etkileşimli kullanım için çalışmasını istiyorsanız PATH'i yeniden sıralayın.
mvn, maven-enforcer-plugin'den requireJavaVersion / requireMavenVersion hakkında bir mesajla başarısız oluyor	JAVA_HOME/PATH'iniz 17'den eski bir JDK'ya işaret ediyor, ya da Maven'ınız 3.8'den eski.	JDK 17+ kurun/işaret edin (java -version 17 veya üzerini göstermeli) ve Maven 3.8+ (mvn -version). Bu projenin pom.xml'i bunu kasıtlı olarak zorunlu kılar, böylece derlemenin derinliklerinde kafa karıştırıcı bir derleme hatası yerine bu açık mesajı alırsınız.
mvn site, "Test Javadoc" raporunda başarısız oluyor: error: No public or protected classes found to document	maven-javadoc-plugin'in varsayılan rapor kümesi test kaynaklarını da Javadoc'lamaya çalışır; bu şablonun test sınıfları kasıtlı olarak paket-özel (package-private) düz JUnit 5 stilindedir, bu yüzden dokümante edecek genel (public) bir şey yoktur.	pom.xml'de zaten düzeltildi: maven-javadoc-plugin için <reportSets> yalnızca ana-kaynak javadoc raporunu ister, test-javadoc'u değil. Kendi raporlama eklentilerinizi eklerseniz test kaynaklarında aynı "genel üye yok" hatasına dikkat edin.
maven-shade-plugin, Discovered module-info.class. Shading will break its strong encapsulation. uyarısı veriyor	logback-classic/logback-core (1.6.x) bir module-info.class taşır; shading (birçok jar'ı tek jar'da birleştirme) bu modül tanımlayıcısıyla uyumsuzdur.	pom.xml'de zaten düzeltildi: bir shade <filter>, module-info.class'ı uber jar'dan hariç tutar. Kalan overlapping resource: META-INF/MANIFEST.MF uyarısı normal shade-plugin davranışıdır (her jar'ın bir manifest'i vardır) ve zararsızdır.
Bir desktop.ini dosyası sürekli yeniden ortaya çıkıyor / git status'ta görünüyor	Bu depo Google Drive for Desktop içinde yaşıyor, o da yönettiği her klasöre gizli bir desktop.ini bırakır.	scriptsdelete-desktop-ini-windows.bat / .sh'yi çalıştırın (init-submodules/update-submodules tarafından da otomatik yapılır). Zaten .gitignore'dadır ama Drive, indeksten silindikten sonra dosyayı yeniden oluşturabilir.
Windows'ta 260 karakterden uzun yollar başarısız oluyor (git, mvn ya da bir eklenti şikayet ediyor)	Windows'un klasik MAX_PATH sınırı, derin bir Maven/Doxygen/JaCoCo çıktı ağacı ile uzun bir Google Drive yolunun birleşimi.	git config --system core.longpaths true (CI iş akışı Actions çalıştırıcısının eşdeğerini zaten yapıyor); Windows 10/11'de, git dışında hâlâ karşılaşıyorsanız Group Policy/registry'de uzun yolları da etkinleştirin (LongPathsEnabled). Google Drive içinde derin bir yerde değil, daha kısa bir yolda derlemek (örn. Drive içine derin gömülü yerine %TEMP%\tmpl-run\<depo>) bunu tamamen önler - bakınız install.md'deki Drive notu.
Bir derleme adımı dosyanın "başka bir işlem tarafından kullanımda" olduğu hatasıyla başarısız oluyor, ya da yazmalar sessizce etkisiz kalıyor	Antivirüs ya da Google Drive for Desktop, target/ altındaki bir dosyayı kilitliyor ya da derleme ortasında yeniden eşitliyor.	Betiği yeniden çalıştırın (bunlar neredeyse her zaman geçicidir); sürerse, Google Drive klasörünün doğrudan içinde değil, yerel, eşitlenmeyen bir klasörde derleyin (%TEMP%\tmpl-run\<depo> / ~/tmpl-run/<depo>) ve politikanız izin veriyorsa derleme/çıktı klasörleriniz için bir antivirüs istisnası ekleyin.
WSL cannot see G:\... / Google Drive yolunuz bir Ubuntu/WSL terminalinden görünmüyor	WSL2, gerçek yerel diskleri bağladığı gibi (/mnt/c, sadece gerçek yerel G: sürücüsü için çalışır, Google Drive'ın sanal dosya sistemi için değil) rastgele eşlenmiş/sanal sürücüleri otomatik bağlamaz.	Önce depoyu yerel bir klasöre kopyalayın: PowerShell'den robocopy "G:\...\eclipse-java-maven-template" "$env:TEMP\tmpl-run\eclipse-java-maven-template" /E; ardından WSL'den cp -r "/mnt/c/Users/<siz>/AppData/Local/Temp/tmpl-run/eclipse-java-maven-template" ~/tmpl-run/ ve orada derleyin. WSL'den test etmek istediğiniz her betik için aynısını yapın.
mvn site, Site model ... is still using the old pre-version 2.0.0 model. You MUST migrate ... yazdırıyor	maven-site-plugin'in (henüz beta olan) 4.x hattında gelecek bir decoration-model değişikliği hakkında bilgilendirici bir uyarı.	Kararlı maven-site-plugin 3.x hattına sabitliyken (bu proje kasıtlı olarak 4.0.0 beta yerine 3.22.0 kullanır) görmezden gelmek güvenlidir. 4.x kararlı bir sürüme ulaştığında yeniden kontrol edin.
9-open-site-* çalıştırırken Address already in use / OSError: [Errno 98]	Bir başka sunucu (önceki bir 9-open-site ya da mkdocs serve) portu hâlâ dinliyor.	Eski terminali kapatın ya da başka port seçin: 9-open-site-windows.bat 8080 / ./9-open-site-linux.sh 8080.
9-open-site-* Python'u bulamadığını söylüyor	PATH'te Python 3 yok ya da yalnız yanlış olanı var.	Python 3.12 kurun (install.md); scripts/detect-python-* py -3.12, py -3.13, ... ve python3 dener.
Bir rapor sayfasındaki <iframe>, file:// ile açıldığında boş kalıyor	Çoğu tarayıcı file://'dan çerçevelenmiş bir sayfayı yüklemeyi reddeder.	Siteyi her zaman 9-open-site-* ile (http://localhost:8000/ adresi) açın, index.html'e çift tıklamayın.
reportgenerator, A fatal error occurred. The required library ... could not be found / You must install .NET to run this application ile başarısız oluyor / doğru SDK kurulu olmasına rağmen eksik bir framework sürümü söylüyor (Linux/WSL)	reportgenerator bir .NET "apphost" çalıştırılabilirdir; çalışma zamanını yalnızca PATH ile değil, DOTNET_ROOT ortam değişkeni üzerinden çözer. Birden fazla .NET SDK'sı olan bir makinede (örn. $HOME/.dotnet altındaki daha yeni kullanıcı-bazlı kurulumun yanında önceden kurulu eski bir 3.1) dotnet PATH'te doğru yeri gösterse bile apphost, DOTNET_ROOT olmadan yanlış - ya da hiç - çalışma zamanı çözebilir.	export DOTNET_ROOT="$HOME/.dotnet" (PATH export'unun yanında) - 4-install-tools-linux.sh, SDK'yı kurduktan sonra tam olarak bu satırı yazdırır.
dotnet tool update --global dotnet-reportgenerator-globaltool, error NU1202: Package ... is not compatible with netcoreapp3.1 ile başarısız oluyor	Aktif dotnet, daha yeni bir framework hedefleyen bir tool paketini (ReportGenerator 5.5+, net8.0/9.0/10.0 hedefler) geri yükleyemeyen eski bir SDK (örn. 3.1).	Önce bir .NET SDK 8+'a kurun/geçin (4-install-tools-linux.sh bunu özellikle kontrol eder ve gerekirse kullanıcı bazında bir tane kurar), ardından tool kurulumunu/güncellemesini yeniden çalıştırın.
Bir .sh betiği bad interpreter: /bin/bash^M: no such file or directory ile başarısız oluyor, ya da gayet normal görünen bir betik için bash -n script.sh unexpected end of file bildiriyor	Dosyada CRLF satır sonları var (her \n'den önce bir \r) - Windows'ta düzenlemeden sonra yaygındır, ya da bu deponun .gitattributes'ı var olmadan önce core.autocrlf=true ile checkout edilmişse. Shebang'ın satır sonundan hemen önceki ya da kapanış done/fi'den hemen önceki bir \r, bash'in dosyayı yanlış ayrıştırmasına neden olabilir.	Bu deponun .gitattributes'ı *.sh'yi (ve pre-commit/pre-push'u) checkout'ta LF'ye zorlar, bu yüzden taze bir git clone etkilenmez. Yine de karşılaşırsanız (örn. clone yerine dosyaları elle kopyaladıysanız), dosyayı yeniden dönüştürün: Linux/WSL'de sed -i 's/\r$//' script.sh, ya da Windows'ta satır sonları LF'ye ayarlı bir editörde açın.
gh release create 403/404 veriyor ya da 10-release-* "gh is not logged in" ile duruyor	oturum yok, yanlış hesap ya da yazma erişimi yok	Bkz. releases.md.
Bir betik ötekini çağırırken '6-build-and-test-windows.bat' is not recognized	ilk satıra bakın: geçerli klasör aranmaz	betikler birbirini call .\6-build-and-test-windows.bat ile çağırır; kendinizinkini de öyle çağırın
mkdocs build --strict A reference to 'guide/xyz.md' is included in the 'nav' configuration, which is not found ile başarısız	mkdocs.yml nav: içinde yazılı bir sayfa yok (yazım hatası ya da üretilen rapor sayfası - assemble.py site çalışmadı)	önce py -3.12 scripts/assemble.py site çalıştırın (7-build-all-* yapar) ya da nav: yolunu düzeltin
No module named material / No module named junit2htmlreport / No module named coverxygen	betikleri çalıştıran Python, paketleri kurduğunuz Python değil	py -3.12 -m pip install --user -r requirements.txt (Windows) ya da python3 -m pip install --user -r requirements.txt (Linux); 4-install-tools-* yapar
Yeni Ubuntu/Debian'da Python paketlerini kurarken error: externally-managed-environment	PEP 668: sistem Python'u pip install --user'ı reddeder	python3 -m pip install --user --break-system-packages -r requirements.txt (4-install-tools-linux.sh'nin yedek yolu) ya da sanal ortam kullanın
mvn derliyor ama jar calculator-app-1.0-SNAPSHOT.jar adlı ve betikler calculator-app-1.1.0.jar'ı bulamıyor	Maven -Drevision olmadan başlatıldı (örn. Eclipse'ten) ve pom.xml varsayılanı project.env'den farklı	betikler üzerinden derleyin (-Drevision=<VERSION> geçirirler) ya da pom.xml <revision>'ını project.env VERSION'ına eşit tutun
reports/<platform>/... klasörleri var ama sitedeki bir rapor sayfası Not available in this build diyor	o rapor (ya da tüm platform) bu makinede derlenmedi	o platform için 7-build-all-<platform> çalıştırın; CI'da ikisi de derlenip birleştirilir
CI: check-links [BROKEN] ... bildiriyor	SİTE sayfalarımızdan birindeki bağlantı olmayan bir dosyayı gösteriyor (üçüncü taraf rapor klasörleri yalnızca uyarı üretir)	iletide adı geçen Markdown dosyasındaki bağlantıyı düzeltip yeniden derleyin