İçeriğe geç

SA-MP Plugin Derleme ve Hata Ayıklama Rehberi

Çalışan bir SA-MP plugin yalnızca compile olmuş dosya değildir. Doğru mimaride üretilmeli, giriş noktalarını export etmeli, sunucunun bulunduğu sistemdeki bağımlılıklarla açılmalı ve Pawn include sürümüyle eşleşmelidir.

Bu son adımda çıktıyı staging sunucusuna taşıyıp sorunları katman katman ayıracağız.

Windows:

Terminal window
cmake -S . -B build/windows -A Win32
cmake --build build/windows --config Release

Linux:

Terminal window
cmake -S . -B build/linux -DCMAKE_BUILD_TYPE=Release
cmake --build build/linux --parallel

Debug build geliştirme sırasında yararlıdır; production dağıtımında gereksiz debug runtime bağımlılığı veya büyük sembol dosyaları istemezsin. Uyarıları görmezden gelme. Pointer dönüşümü, signed/unsigned karşılaştırması ve kullanılmayan hata sonucu plugin kodunda gerçek bug işareti olabilir.

Windows Developer Command Prompt:

Terminal window
dumpbin /headers build\windows\Release\starter.dll

Çıktıdaki machine alanı x86 hedefini göstermelidir. Linux’ta:

Terminal window
file build/linux/starter.so

32 bit sunucuya 64 bit plugin verirsen server.cfg doğru olsa bile dosya yüklenmez. Dosya adını veya plugins satırını değiştirmek mimari uyuşmazlığını çözmez; yeniden doğru target ile derlemelisin.

Windows:

Terminal window
dumpbin /exports build\windows\Release\starter.dll

En az şu adları görmelisin:

Supports
Load
Unload
AmxLoad
AmxUnload

SUPPORTS_PROCESS_TICK kullanıyorsan ProcessTick, sampgdk ile C++ callback yazdıysan ilgili callback adları da listede olmalıdır.

Linux:

Terminal window
nm -D build/linux/starter.so

İsimler C++ tarafından değiştirilmiş uzun semboller olarak görünüyorsa export makroları veya C linkage yanlış olabilir. Giriş noktalarını rehberdeki PLUGIN_EXPORT ve PLUGIN_CALL biçimiyle tanımla.

4. Çalışma zamanı bağımlılıklarını kontrol et

Bölüm başlığı “4. Çalışma zamanı bağımlılıklarını kontrol et”

Linux’ta eksik dinamik kütüphaneleri gör:

Terminal window
ldd build/linux/starter.so

not found görünen bağımlılık production sunucusunda çözülmeden plugin yüklenemez. Windows’ta da MSVC runtime ve üçüncü taraf DLL’ler hedef sistemde bulunmalıdır.

Mümkün olduğunda gereksiz bağımlılık ekleme. Bir library’yi statik bağlamak dağıtımı kolaylaştırabilir, ancak lisansını, binary boyutunu ve hedef sistem uyumluluğunu ayrıca değerlendir.

Minimum paket şu dosyalardan oluşur:

starter-1.0.0/
├── plugins/
│ ├── starter.dll
│ └── starter.so
├── pawno/
│ └── include/
│ └── starter.inc
├── CHANGELOG.md
└── README.md

Windows ve Linux binary’lerini aynı makinede kullanmak için değil, tek sürüm paketinde iki platform sunmak için birlikte listeliyoruz. Kullanıcı yalnızca kendi sunucusuna uygun dosyayı kopyalar.

.inc ile binary aynı API sürümüne ait olmalıdır. Include yeni bir native bildirip eski DLL dağıtılırsa Pawn compile olur fakat script yüklenirken native bulunamaz.

Production yerine temiz bir test sunucusunda şu sırayı izle:

  1. plugin dosyasını plugins/ klasörüne kopyala,
  2. server.cfg plugins satırını güncelle,
  3. starter.inc ile küçük bir filterscript derle,
  4. sunucuyu başlat ve server_log.txt dosyasını kontrol et,
  5. her native için bir başarılı, bir geçersiz girdi dene,
  6. filterscript’i kaldırıp yeniden yükleyerek AmxUnload akışını test et,
  7. sunucuyu kapatıp worker thread ve kaynakların temiz kapandığını doğrula.

İlk test gamemode yerine küçük filterscript ile yapılırsa plugin sorununu oyun modunun geri kalanından ayırmak kolaylaşır.

Belirti Olası neden İlk kontrol
Plugin listede hiç görünmüyor Yanlış dosya adı veya server.cfg satırı plugins/ yolu ve işletim sistemi uzantısı
Mimari uyumsuzluğu mesajı x64 plugin, x86 sunucu veya uyumsuz library dumpbin /headers ya da file çıktısı
Giriş noktası bulunamadı .def eksik veya export imzası yanlış dumpbin /exports ya da nm -D
DLL/SO açılamıyor Çalışma zamanı bağımlılığı eksik Windows bağımlılıkları veya ldd
Runtime error 19 Native kayıtlı değil veya plugin yüklenmedi Log, .inc adı ve pluginNatives kaydı
amx_Register sırasında çökme pAMXFunctions atanmamış ya da geçersiz Load içindeki PLUGIN_DATA_AMX_EXPORTS ataması
Callback çalışmıyor Public bulunmuyor, push sırası veya export hatalı amx_FindPublic sonucu ve callback imzası
Kapanışta sunucu takılıyor Worker thread bitmiyor Stop sinyali, bloklayan işlem ve join

Hata, Pawn script’in ihtiyaç duyduğu native fonksiyonu yükleme sırasında bulamadığını gösterir. Şu zinciri sırayla kontrol et:

plugin dosyası yüklendi mi?
-> Load true döndü mü?
-> Supports, AMX_NATIVES bayrağını içeriyor mu?
-> AmxLoad çağrıldı mı?
-> amx_Register başarı döndürdü mü?
-> .inc adı kayıt dizisindeki adla aynı mı?

Sorunu #pragma unused veya native bildirimini silerek gizleme. Script fonksiyonu gerçekten kullanıyorsa plugin ile include sürümünü eşleştir.

Native kodunda erişim ihlali varsa önce şu noktaları incele:

  • params[0] kontrol edilmeden params[2] gibi alanlar okunuyor mu?
  • amx_GetAddr hata döndürdüğü halde pointer dereference ediliyor mu?
  • Pawn dizisinin verdiği size sınırı aşılıyor mu?
  • amx_Release yanlış adresle veya callback tamamlanmadan çağrılıyor mu?
  • unload edilmiş AMX* listede tutuluyor mu?
  • worker thread AMX veya SA-MP API çağrısı yapıyor mu?

Log’u son güvenli adımdan hemen önce yaz. Sorun tek native’e indikten sonra geçerli en küçük girdiyle tekrar üret. Rastgele null kontrolü eklemek yerine pointer’ın nerede geçersiz hale geldiğini bul.

Dışarı export edilen giriş noktalarında şu kuralları uygula:

  • C++ exception’ını plugin sınırının dışına kaçırma,
  • Pawn’a std::string, C++ reference veya nesne pointer’ı döndürme,
  • bütün Pawn verisini cell ve AMX API üzerinden dönüştür,
  • Load kısmen başarısızsa açılmış kaynakları kapat,
  • AmxUnload sonrasında o AMX için bekleyen işleri iptal et,
  • Unload tamamlandığında yaşayan thread bırakma.

Plugin içi kodda RAII, std::vector ve std::string kullanabilirsin. Sınırın dışına yalnızca SDK’nin beklediği sade fonksiyon imzaları çıkar.

Bir native kaldırmak, parametre sırasını değiştirmek veya dönüş anlamını değiştirmek API kırılmasıdır. Binary ve starter.inc sürümünü birlikte artır. Yayınlamadan önce:

  • temiz ortamda Windows ve Linux Release build al,
  • export ve mimari kontrollerini çalıştır,
  • eski include ile uyumluluğu bilinçli test et,
  • yeni native ve hata davranışlarını README içinde açıkla,
  • log satırında plugin adı ve sürümünü göster,
  • staging sunucusunda yükleme, script reload ve kapanış testlerini tamamla.

Artık boş bir C++ projesinden başlayarak SA-MP’nin yükleyebildiği plugin üretebilir, Pawn’a native API sunabilir, AMX verisini güvenle çevirebilir, özel callback gönderebilir ve asenkron işi ana thread’e taşıyabilirsin.

Bir sonraki gerçek proje için küçük başla: tek bir sorunu çözen iki veya üç native tasarla, dönüş sözleşmelerini .inc yanında yaz ve yeni özellik eklemeden önce iki platformda smoke test et.

Plugin geliştirme yol haritasına dön →