Server sumber

Server sumber memungkinkan klien untuk mengambil versi file sumber yang tepat yang digunakan untuk membangun aplikasi. Karena kode sumber untuk modul dapat berubah antara versi dan selama bertahun-tahun, penting untuk melihat kode sumber seperti yang ada ketika versi modul yang dimaksud dibangun.

Server sumber mengambil file yang sesuai dari kontrol sumber. Untuk menggunakan server sumber, aplikasi harus telah diindeks sumber.

Pengindeksan Sumber

Sistem pengindeksan sumber adalah kumpulan file yang dapat dieksekusi dan skrip Perl. Skrip Perl memerlukan Perl 5.6 atau yang lebih tinggi.

Umumnya, biner diindeks sumber selama proses build setelah aplikasi dibuat. Informasi yang diperlukan oleh server sumber disimpan dalam file PDB.

Server sumber saat ini dikirim dengan skrip yang harus bekerja dengan sistem kontrol sumber berikut.

• Team Foundation Server
• Perforce
• Sumber Visual Brankas
• CVS
• Subversion

Anda juga dapat membuat skrip kustom untuk mengindeks kode Anda untuk sistem kontrol sumber yang berbeda.

Tabel berikut mencantumkan alat server sumber.

Alat	Deskripsi
Srcsrv.ini	File ini adalah daftar master dari semua server kontrol sumber. Setiap entri memiliki format berikut:MYSERVER=serverinfo Saat menggunakan Perforce, info server terdiri dari jalur jaringan lengkap ke server, diikuti oleh titik dua, diikuti dengan nomor port yang digunakannya. Misalnya: MYSERVER=machine.corp.company.com:1666 File ini dapat diinstal pada komputer yang menjalankan debugger. Ketika server sumber dimulai, server melihat Srcsrv.ini untuk nilai; nilai-nilai ini akan mengambil alih informasi yang terkandung dalam file PDB. Ini memungkinkan pengguna untuk mengonfigurasi debugger untuk menggunakan server kontrol sumber alternatif pada waktu debug. Untuk informasi selengkapnya, lihat contoh Srcsrv.ini diinstal dengan alat server sumber.
Ssindex.cmd	Skrip ini membangun daftar file yang diperiksa ke kontrol sumber bersama dengan informasi versi setiap file. Ini menyimpan subset informasi ini dalam file .pdb yang dihasilkan saat Anda membangun aplikasi. Skrip menggunakan salah satu modul Perl berikut untuk berinteraksi dengan kontrol sumber: P4.pm (Perforce) atau Vss.pm (Visual Source Brankas). Untuk informasi selengkapnya, jalankan skrip dengan -? Atau-?? (bantuan verbose) atau periksa skrip.
Srctool.exe	Utilitas ini mencantumkan semua file yang diindeks dalam file .pdb. Untuk setiap file, file mencantumkan jalur lengkap, server kontrol sumber, dan nomor versi file. Anda dapat menggunakan informasi ini untuk mengambil file tanpa menggunakan server sumber. Untuk informasi selengkapnya, jalankan utilitas dengan /? pilihan.
Pdbstr.exe	Utilitas ini digunakan oleh skrip pengindeksan untuk menyisipkan informasi kontrol versi ke dalam aliran alternatif "srcsrv" dari file .pdb target. Ini juga dapat membaca aliran apa pun dari file .pdb. Anda dapat menggunakan informasi ini untuk memverifikasi bahwa skrip pengindeksan berfungsi dengan baik. Untuk informasi selengkapnya, jalankan utilitas dengan /? pilihan.

 

Mengambil File Sumber

API DbgHelp menyediakan akses ke fungsionalitas server sumber melalui fungsi SymGetSourceFile. Untuk mengambil nama file sumber yang akan diambil, panggil fungsi SymEnumSourceFiles atau SymGetLineFromAddr64.

Menggunakan Server Sumber dengan Debugger

Untuk menggunakan server sumber dengan WinDbg, KD, NTSD, atau CDB, pastikan Anda telah menginstal versi terbaru dari paket Alat Penelusuran Kesalahan untuk Windows (versi 6.3 atau yang lebih baru). Kemudian, sertakan srv* dalam perintah .srcpath sebagai berikut:

.srcpath srv*;c:\mysource

Perhatikan bahwa contoh ini juga menyertakan jalur sumber tradisional. Jika debugger tidak dapat mengambil file dari server sumber, debugger akan mencari jalur yang ditentukan.

Jika file sumber diambil oleh server sumber, file tersebut akan tetap berada di hard drive Anda setelah sesi penelusuran kesalahan selesai. File sumber disimpan secara lokal di subdirektori src alat debugging untuk direktori penginstalan Windows.

Blok Data Server Sumber

Server sumber bergantung pada dua blok data dalam file PDB.

• Daftar file sumber. Membangun modul secara otomatis membuat daftar jalur yang sepenuhnya memenuhi syarat ke file sumber yang digunakan untuk membangun modul.
• Blok data. Mengindeks sumber seperti yang dijelaskan sebelumnya menambahkan aliran alternatif ke file PDB bernama "srcsrv". Skrip yang menyisipkan data ini bergantung pada proses build tertentu dan sistem kontrol sumber yang digunakan.

Dalam spesifikasi bahasa versi 1, blok data dibagi menjadi tiga bagian: ini, variabel, dan file sumber. Ini 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 diperluas.

%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 berisi variabel yang menjelaskan persyaratan. Skrip pengindeksan dapat menambahkan sejumlah variabel ke bagian ini. Berikut adalah contoh:

VERSI

Versi spesifikasi bahasa. Variabel ini diperlukan.

VERCTL

String yang menjelaskan produk kontrol sumber. Variabel ini bersifat opsional.

DATETIME

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

Bagian variabel 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 adalah variabel yang diperlukan.

SRCSRVENV

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

Bagian file sumber 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. Misalnya, baris berikut:

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 versi. Namun, sebagian besar sistem kontrol sumber mendukung pelabelan file singgah status sumber untuk build tertentu dapat dipulihkan. Oleh karena itu, Anda dapat secara bergantian menggunakan label untuk build. 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%) cetak -o %srcsrvtrg% -q %depot%/%var3%@%label%

Cara Kerja Server Sumber

Klien server sumber diimplementasikan dalam Symsrv.dll. Klien tidak mengekstrak informasi langsung dari file PDB; ini menggunakan handler simbol seperti yang diimplementasikan dalam Dbghelp.dll. Ini pada dasarnya adalah mesin substitusi variabel rekursif yang membuat baris perintah yang dapat digunakan untuk mengekstrak file sumber yang tepat dari sistem kontrol sumber. Kode Anda tidak boleh memanggil Symsrv.dll secara langsung. Untuk mengintegrasikan fungsionalitasnya ke dalam aplikasi Anda, gunakan fungsi SymGetSourceFile.

Versi pertama server sumber berfungsi sebagai berikut. Perilaku ini dapat berubah dalam versi mendatang.

• Klien memanggil fungsi SrcSrvInit dengan jalur target yang akan digunakan sebagai basis untuk semua ekstraksi file sumber. Ini menyimpan jalur ini dalam variabel TARG.
• Klien mengekstrak aliran Srcsrv dari PDB ketika PDB modul dimuat dan memanggil fungsi SrcSrvLoadModule untuk meneruskan blok data ke server sumber.
• Ketika Dbghelp mengambil file sumber, klien memanggil fungsi SrcSrvGetFile untuk mengambil file sumber dari kontrol sumber.
• Server sumber mencari entri file sumber di blok data untuk entri yang cocok dengan file yang diminta. Ini mengisi VAR1 ke VARn dengan konten entri file sumber. Selanjutnya, ini memperluas variabel SRCSRVTRG menggunakan VAR1 ke VARn. Jika file sudah ada di lokasi ini, file mengembalikan lokasi ke pemanggil. Jika tidak, ini memperluas variabel SRCSRVCMD untuk membangun perintah yang diperlukan untuk mengambil file dari kontrol sumber dan menyalinnya ke lokasi target. Akhirnya, ia menjalankan perintah ini.

Membuat Modul Penyedia Kontrol Sumber

Server sumber mencakup modul penyedia untuk Perforce (p4.pm) dan Brankas Sumber Visual (vss.pm). Untuk membuat modul penyedia Anda sendiri, Anda harus menerapkan serangkaian antarmuka berikut.

$module::SimpleUsage()

Tujuan: Menampilkan informasi penggunaan modul sederhana ke STDOUT.

Parameter: Tidak ada

Mengembalikan nilai: Tidak ada

$module::VerboseUsage()

Tujuan: Menampilkan informasi penggunaan modul mendalam ke STDOUT.

Parameter: Tidak ada

Mengembalikan nilai: Tidak ada

$objref = $module::new(@CommandArguments)

Tujuan: Menginisialisasi instans modul penyedia.

Parameter: Semua @ARGV argumen yang tidak dikenali oleh SSIndex.cmd sebagai argumen umum.

Mengembalikan nilai: Referensi yang dapat digunakan dalam operasi selanjutnya.

$objref-GatherFileInformation>($SourcePath, $ServerHashReference)

Tujuan: Memungkinkan modul mengumpulkan informasi pengindeksan sumber yang diperlukan untuk direktori yang ditentukan oleh parameter $SourcePath. Modul tidak boleh berasumsi bahwa entri ini hanya akan dipanggil sekali untuk setiap instans objek, karena SSIndex.cmd dapat memanggilnya beberapa kali untuk jalur yang berbeda.

Parameter: (1) Direktori lokal yang berisi sumber yang akan diindeks. (2) Referensi ke hash yang berisi semua entri dari file Srcsrv.ini yang ditentukan.

Mengembalikan nilai: Tidak ada

($VariableHashReference, $FileEntry) = $objref-GetFileInfo>($LocalFile)

Tujuan: Menyediakan informasi yang diperlukan untuk mengekstrak satu file tertentu dari sistem kontrol sumber.

Parameter: Nama file yang sepenuhnya memenuhi syarat

Mengembalikan nilai: (1) Referensi hash dari variabel yang diperlukan untuk menginterpretasikan $FileEntry yang dikembalikan. SSIndex.cmd cache variabel ini untuk setiap file sumber yang digunakan oleh satu file debug untuk mengurangi jumlah informasi yang ditulis ke aliran indeks sumber. (2) Entri file yang akan ditulis ke aliran indeks sumber untuk memungkinkan SrcSrv.dll mengekstrak file ini dari kontrol sumber. Format yang tepat dari baris ini khusus untuk sistem kontrol sumber.

$TextString = $objref-LongName>()

Tujuan: Menyediakan string deskriptif untuk mengidentifikasi penyedia kontrol sumber kepada pengguna akhir.

Parameter: Tidak ada

Mengembalikan nilai: Nama deskriptif sistem kontrol sumber.

@StreamVariableLines = $objref-SourceStreamVariables>()

Tujuan: Memungkinkan penyedia kontrol sumber untuk menambahkan variabel khusus kontrol sumber ke aliran sumber untuk setiap file debug. Modul sampel menggunakan metode ini untuk menulis variabel EXTRACT_CMD dan EXTRACT_TARGET yang diperlukan.

Parameter: Tidak ada

Mengembalikan nilai: Daftar entri untuk variabel aliran sumber.