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.
1. Release çıktısı al
Bölüm başlığı “1. Release çıktısı al”Windows:
cmake -S . -B build/windows -A Win32cmake --build build/windows --config ReleaseLinux:
cmake -S . -B build/linux -DCMAKE_BUILD_TYPE=Releasecmake --build build/linux --parallelDebug 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.
2. Mimariyi doğrula
Bölüm başlığı “2. Mimariyi doğrula”Windows Developer Command Prompt:
dumpbin /headers build\windows\Release\starter.dllÇıktıdaki machine alanı x86 hedefini göstermelidir. Linux’ta:
file build/linux/starter.so32 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.
3. Export edilen fonksiyonları kontrol et
Bölüm başlığı “3. Export edilen fonksiyonları kontrol et”Windows:
dumpbin /exports build\windows\Release\starter.dllEn az şu adları görmelisin:
SupportsLoadUnloadAmxLoadAmxUnloadSUPPORTS_PROCESS_TICK kullanıyorsan ProcessTick, sampgdk ile C++ callback yazdıysan ilgili callback adları da listede olmalıdır.
Linux:
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:
ldd build/linux/starter.sonot 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.
5. Dağıtım paketini hazırla
Bölüm başlığı “5. Dağıtım paketini hazırla”Minimum paket şu dosyalardan oluşur:
starter-1.0.0/├── plugins/│ ├── starter.dll│ └── starter.so├── pawno/│ └── include/│ └── starter.inc├── CHANGELOG.md└── README.mdWindows 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.
6. Staging sunucusunda smoke test yap
Bölüm başlığı “6. Staging sunucusunda smoke test yap”Production yerine temiz bir test sunucusunda şu sırayı izle:
- plugin dosyasını
plugins/klasörüne kopyala, server.cfgplugins satırını güncelle,starter.incile küçük bir filterscript derle,- sunucuyu başlat ve
server_log.txtdosyasını kontrol et, - her native için bir başarılı, bir geçersiz girdi dene,
- filterscript’i kaldırıp yeniden yükleyerek
AmxUnloadakışını test et, - 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.
SA-MP plugin yüklenmiyor: hata tablosu
Bölüm başlığı “SA-MP plugin yüklenmiyor: hata tablosu”| 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 |
Runtime error 19 nasıl çözülür?
Bölüm başlığı “Runtime error 19 nasıl çözülür?”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.
Sunucu çökmesini daralt
Bölüm başlığı “Sunucu çökmesini daralt”Native kodunda erişim ihlali varsa önce şu noktaları incele:
params[0]kontrol edilmedenparams[2]gibi alanlar okunuyor mu?amx_GetAddrhata döndürdüğü halde pointer dereference ediliyor mu?- Pawn dizisinin verdiği
sizesınırı aşılıyor mu? amx_Releaseyanlış 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.
Plugin ABI sınırını koru
Bölüm başlığı “Plugin ABI sınırını koru”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
cellve AMX API üzerinden dönüştür, Loadkısmen başarısızsa açılmış kaynakları kapat,AmxUnloadsonrasında o AMX için bekleyen işleri iptal et,Unloadtamamlandığı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.
Sürümleme ve yayın kontrolü
Bölüm başlığı “Sürümleme ve yayın kontrolü”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.
Rehber tamamlandı
Bölüm başlığı “Rehber tamamlandı”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.