Spesifikasi Bahasa 1

Nota

Topik ini menjelaskan operasi internal SrcSrv. Untuk informasi umum tentang cara kerja jalur sumber, lihat Jalur Sumber. Untuk informasi tentang menggunakan SrcSrv, lihat Menggunakan SrcSrv. Untuk menentukan operasi pemuatan sumber saat ini di lingkungan Anda, aktifkan pemuatan sumber yang bising seperti yang dijelaskan dalam .srcnoisy (Pemuatan Sumber Berisik)

Versi pertama SrcSrv berfungsi sebagai berikut. (Perilaku ini dapat berubah dalam versi mendatang.)

Pertama, klien memanggil SrcSrvInit dengan jalur target yang akan digunakan sebagai basis untuk semua ekstraksi file sumber. Jalur ini disimpan dalam variabel khusus TARG.

Ketika DbgHelp memuat file .pdb modul, DbgHelp mengekstrak aliran SrcSrv dari file .pdb dan meneruskan blok data ini ke SrcSrv dengan memanggil SrcSrvLoadModule.

Kemudian ketika DbgHelp perlu mendapatkan file sumber, DbgHelp memanggil SrcSrvGetFile untuk mengambil file sumber tertentu dari kontrol versi.

SrcSrv meninjau semua entri file sumber di blok data untuk entri yang cocok dengan spesifikasi sumber yang diminta. Kecocokan ini ditemukan di VAR1.

Setelah SrcSrv menemukan entri, SrcSrv mengisi variabel khusus (VAR1, VAR2, dll.) dengan konten entri file sumber ini. Kemudian variabel SRCSRVTRG diselesaikan menggunakan variabel khusus ini.

Berikut ini menunjukkan bagaimana variabel SRCSRVTRG diselesaikan menggunakan variabel khusus. Kami berasumsi bahwa jalur sumber masih:

c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3

Setiap baris menunjukkan resolusi satu variabel khusus lagi. Variabel yang ditebalkan.

SRCSRVTRG=%sdtrg% 
SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\%fnbksl%( sdktools/debuggers/srcsrv/shell.cpp )\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\ sdktools\debuggers\srcsrv\shell.cpp\%var4%\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%(%var1%)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\%fnfile%( c:\db\srcsrv\shell.cpp)
c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp

Perhatikan bagaimana jalur target yang dihasilkan ini unik dan tidak memungkinkan dua versi file yang sama diekstrak ke lokasi yang sama.

SrcSrv sekarang melihat apakah file sudah ada. Jika ya, SrcSrv mengembalikan lokasi ke pemanggil. Jika tidak, SrcSrv membangun perintah eksekusi untuk mengekstrak file dengan menyelesaikan SRCSRVCMD.

Dalam contoh berikut, setiap baris menunjukkan resolusi satu variabel khusus lagi. Variabel yang sudah diselesaikan dicetak tebal.

DEPOT=//depot 
WIN_SDKTOOLS= sserver.microsoft.com:4444 
SRCSRVCMD=%sdcmd% 
SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4% 
sd.exe -p %fnvar%(WIN_SDKTOOLS) print -o %srcsrvtrg% -q %depot%/%var3%#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o %srcsrvtrg% -q %depot%/%var3%#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q %depot%/%var3%#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/%var3%#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#%var4% 
sd.exe -p sserver.microsoft.com:4444  print -o c:\src\WIN_SDKTOOLS\sdktools\debuggers\srcsrv\shell.cpp\3\shell.cpp -q //depot/ sdktools/debuggers/srcsrv/shell.cpp#3 

Sekarang SrcSrv menjalankan perintah ini. Jika hasil perintah ini adalah file di lokasi yang diharapkan, jalur ini dikembalikan ke pemanggil.

Perhatikan bahwa jika variabel tidak dapat diselesaikan, upaya dilakukan untuk mencarinya sebagai variabel lingkungan OS. Jika gagal, nama variabel dihapus dari teks yang sedang diproses.

Dua karakter tanda persen berturut-turut ditafsirkan sebagai tanda persen tunggal.

Blok Data Server Sumber

SrcSrv mengandalkan dua blok data dalam file .pdb, daftar file sumber, dan blok data.

Daftar file sumber dibuat secara otomatis saat modul dibuat. Daftar ini berisi jalur yang sepenuhnya memenuhi syarat ke file sumber yang digunakan untuk membangun modul.

Blok data dibuat selama pengindeksan sumber. Saat ini, aliran alternatif bernama "srcsrv" ditambahkan ke file .pdb. Skrip yang menyisipkan data ini bergantung pada proses build tertentu dan sistem kontrol sumber yang digunakan.

Blok data dibagi menjadi tiga bagian: ini, variabel, dan file sumber. Blok data memiliki sintaks berikut.

SRCSRV: ini ------------------------------------------------ 
VERSION=1
VERCTRL=<source_control_str>
DATETIME=<date_time_str>
SRCSRV: variables ------------------------------------------ 
SRCSRVTRG=%sdtrg% 
SRCSRVCMD=%sdcmd% 
SRCSRVENV=var1=string1\bvar2=string2 
DEPOT=//depot 
SDCMD=sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%#%var4% 
SDTRG=%targ%\%var2%\%fnbksl%(%var3%)\%var4%\%fnfile%(%var1%) 
WIN_SDKTOOLS= sserver.microsoft.com:4444 
SRCSRV: source files --------------------------------------- 
<path1>*<var2>*<var3>*<var4> 
<path2>*<var2>*<var3>*<var4> 
<path3>*<var2>*<var3>*<var4> 
<path4>*<var2>*<var3>*<var4> 
SRCSRV: end ------------------------------------------------

Semua teks ditafsirkan secara harfiah, kecuali untuk teks yang diapit dalam tanda persen (%). Teks yang diapit dalam tanda persen diperlakukan sebagai nama variabel untuk diselesaikan secara rekursif, kecuali itu adalah salah satu fungsi berikut:

%fnvar%()
Teks parameter harus diapit dalam tanda persen dan diperlakukan sebagai variabel yang akan diselesaikan.

%fnbksl%()
Semua garis miring ke depan (/) dalam teks parameter harus diganti dengan garis miring mundur ().

%fnfile%()
Semua informasi jalur dalam teks parameter harus dilucuti, hanya menyisakan nama file.

Bagian [ini] dari blok data berisi variabel yang menjelaskan persyaratan. Skrip pengindeksan dapat menambahkan sejumlah variabel ke bagian ini. Berikut ini adalah contohnya:

VERSI
Versi spesifikasi bahasa. Variabel ini diperlukan. Jika Anda mengembangkan skrip berdasarkan spesifikasi bahasa saat ini, atur nilai ini ke 1. Kode klien SrcSrv tidak mencoba menjalankan skrip apa pun yang memiliki nilai lebih besar dari kodenya sendiri. Versi SrcSrv saat ini menggunakan nilai 2.

VERCTRL
String yang menjelaskan sistem kontrol versi sumber. Variabel ini bersifat opsional.

DATETIME
String yang menunjukkan tanggal dan waktu file .pdb diproses. Variabel ini bersifat opsional.

Bagian [variabel] dari blok data berisi variabel yang menjelaskan cara mengekstrak file dari kontrol sumber. Ini juga dapat digunakan untuk menentukan teks yang umum digunakan sebagai variabel untuk mengurangi ukuran blok data.

SRCSRVTRG
Menjelaskan cara membangun jalur target untuk file yang diekstrak. Ini adalah variabel yang diperlukan.

SRCSRVCMD
Menjelaskan cara membuat perintah untuk mengekstrak file dari kontrol sumber. Ini termasuk nama file yang dapat dieksekusi dan parameter baris perintahnya. Ini diperlukan jika ada perintah ekstraksi yang harus dijalankan.

SRCSRVENV
Mencantumkan variabel lingkungan yang akan dibuat selama ekstraksi file. Ini adalah string. Pisahkan beberapa entri dengan karakter backspace (\b). Ini adalah variabel opsional.

SRCSRVVERCTRL
Menentukan sistem kontrol versi yang digunakan. Untuk Perforce, ini memang perlu. Untuk Team Foundation Server, ini adalah tfs. Variabel ini digunakan untuk mempertahankan kesalahan server. Ini adalah variabel opsional.

SRCSRVVERRDESC
Menentukan teks yang akan ditampilkan ketika klien kontrol versi tidak dapat menghubungi server yang berisi file sumber untuk diekstrak. SrcSrv menggunakan nilai ini untuk memeriksa masalah koneksi. Ini adalah variabel opsional.

SRCSRVERRVAR
Menunjukkan variabel mana dalam entri file yang sesuai dengan server kontrol versi. Ini digunakan oleh SrcSrv untuk mengidentifikasi perintah yang tidak berfungsi, berdasarkan kegagalan sebelumnya. Format teks adalah varX di mana X adalah jumlah variabel yang ditunjukkan. Ini adalah variabel opsional.

Bagian [file sumber] dari blok data berisi entri untuk setiap file sumber yang telah diindeks. Konten setiap baris ditafsirkan sebagai variabel dengan nama VAR1, VAR2, VAR3, dan sebagainya hingga VAR10. Variabel dipisahkan oleh tanda bintang. VAR1 harus menentukan jalur yang sepenuhnya memenuhi syarat ke file sumber seperti yang tercantum di tempat lain dalam file .pdb. Contohnya:

c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3 

ditafsirkan sebagai berikut:

VAR1=c:\proj\src\file.cpp
VAR2=TOOLS_PRJ
VAR3=tools/mytool/src/file.cpp
VAR4=3

Dalam contoh ini, VAR4 adalah nomor revisi. Namun, sebagian besar sistem kontrol sumber mendukung pelabelan file singgah status sumber untuk build tertentu dapat dipulihkan. Oleh karena itu, Anda dapat menggunakan label untuk pembuatan perangkat lunak. Blok data sampel dapat dimodifikasi untuk berisi variabel seperti berikut ini:

LABEL=BUILD47 

Kemudian, dengan mengasumsikan sistem kontrol sumber menggunakan tanda (@) untuk menunjukkan label, Anda dapat memodifikasi variabel SRCSRVCMD sebagai berikut:

sd.exe -p %fnvar%(%var2%) print -o %srcsrvtrg% -q %depot%/%var3%@%label%

Menangani Kesalahan Server

Terkadang klien tidak dapat mengekstrak file apa pun sama sekali dari server kontrol versi tunggal. Ini bisa karena server tidak berfungsi dan keluar dari jaringan atau karena pengguna tidak memiliki hak istimewa yang sesuai untuk mengakses sumber. Namun, waktu yang dihabiskan untuk mencari sumber ini dapat memperlambat proses secara signifikan. Dalam situasi ini, yang terbaik adalah menonaktifkan upaya untuk mengekstrak dari sumber yang telah terbukti tidak tersedia.

Setiap kali SrcSrv gagal mengekstrak file, SrcSrv memeriksa teks output yang dihasilkan oleh perintah . Jika ada bagian dari perintah ini yang berisi cocokan persis untuk konten SRCSRVERRDESC, semua perintah mendatang ke server kontrol versi yang sama akan dilewatkan. Perhatikan bahwa Anda dapat menentukan beberapa string kesalahan dengan menambahkan angka atau teks arbitrer ke akhir nama variabel SRCSRVERRDESC. Berikut adalah contohnya:

SRCSRVERRDESC=lime: server not found
SRCSRVERRDESC_2=pineapple: network error

Identitas server diperoleh dari SRCSRVERRVAR. Jadi jika SRCSRVERRVAR berisi "var2" dan entri file dalam file .pdb terlihat seperti ini:

c:\proj\src\file.cpp*TOOLS_PRJ*tools/mytool/src/file.cpp*3

semua upaya di masa mendatang untuk mendapatkan sumber menggunakan entri file yang berisi "TOOLS_PRJ" dalam variabel 2 dilewati.

Anda juga dapat menambahkan indikator kesalahan pada klien debugger dengan mengedit Srcsrv.ini. Lihat contoh versi srcsrv.ini yang disertakan untuk detailnya.