Unduh ycmd - Unduh Kode Sumber ycmd

ycmd

Sumber daya lainnya

1.0.0

Unduh

YCMD: Server Lengkap & Pemahaman Kode

YCMD adalah server yang menyediakan API untuk pelengkapan kode dan kasus penggunaan kode-komprehensi lainnya seperti perintah Goto semantik (dan lainnya). Untuk filetypes tertentu, YCMD juga dapat memberikan kesalahan dan peringatan diagnostik.

YCMD awalnya merupakan bagian dari basis kode YouCompleteme, tetapi telah dibagi menjadi proyek terpisah sehingga dapat digunakan dalam editor selain VIM.

Periksa dokumentasi API jika Anda ingin mengimplementasikan klien. Cara yang baik untuk mempelajari cara berinteraksi dengan YCMD adalah dengan membaca (dan menjalankan) file example_client.py . Lihat Folder Contoh ReadMe untuk detail tentang cara menjalankan Contoh Klien.

Klien YCMD yang Dikenal:

YouCompleteme: Klien VIM, stabil dan memaparkan semua fitur YCMD.
Emacs-YCMD: Klien Emacs.
You-Complete-Me: Klien Atom.
YCMDCompletion: Klien Sublime
Sublime-YCMD: Sublime Text 3 Client.
Kak-ycmd: Klien Kakoune.
You-complete-me: klien vscode.
GYCM: Klien Geany.
Nano-ycmd: Klien Nano GNU.

Jangan ragu untuk mengirim permintaan tarik menambahkan tautan ke klien Anda di sini jika Anda telah membangunnya.

Bangunan

Jika Anda ingin mengembangkan YCMD, lihat instruksi untuk menjalankan tes.

Ini semua untuk Ubuntu Linux. Detail tentang menjalankan YCMD di OS lain dapat ditemukan dalam instruksi YCM (abaikan bagian khusus VIM). Perhatikan bahwa YCMD berjalan di Python 3.8.0+.

Pertama, instal dependensi minimal:

 sudo apt install build-essential cmake python3-dev

Selanjutnya, instal dependensi spesifik bahasa yang Anda butuhkan:

sudo apt install golang-go untuk pergi.
sudo apt install npm untuk javascript dan ncript.
sudo apt install mono-devel untuk c#.
sudo apt install openjdk-8-jre untuk java.

Ketika Anda pertama kali mengkloning repositori, Anda harus memperbarui submodul:

 git submodule update --init --recursive

Kemudian jalankan python3 build.py --all atau salah satu pelengkap spesifik yang terdaftar oleh python3 build.py --help . Ini seharusnya membuatmu pergi.

Untuk instruksi yang lebih rinci tentang membangun YCMD, lihat instruksi YCM (abaikan bagian khusus VIM).

Kompiler yang didukung

GCC 8 dan yang lebih baru
Dentang 7 dan yang lebih baru
Microsoft Visual Studio 2017 V 15.7 dan yang lebih baru

Catatan API

Semua string masuk dan keluar dari server disandikan UTF-8.
Semua baris berakhir dengan n .
Semua nomor baris dan kolom berbasis 1, bukan berbasis 0. Mereka juga byte offset, bukan offset codepoint unicode.
Semua jalur file penuh, jalur absolut.
Semua permintaan ke server harus menyertakan HMAC di header HTTP x-ycm-hmac . HMAC dihitung dari rahasia bersama yang diteruskan ke server pada startup dan badan permintaan/respons. Algoritma Digest adalah SHA-256. Server juga akan menyertakan HMAC dalam tanggapannya; Anda harus memverifikasi sebelum menggunakan respons. Lihat example_client.py untuk melihat bagaimana hal itu dilakukan.
API didokumentasikan dalam kesombongan dan diterbitkan di situs web.

Bagaimana YCMD bekerja

Ada beberapa mesin penyelesaian di YCMD. Yang paling mendasar adalah pelengkap berbasis pengidentifikasi yang mengumpulkan semua pengidentifikasi dalam file yang disediakan dalam permintaan penyelesaian, file lain dari filetype yang sama yang disediakan sebelumnya dan setiap file tag yang diproduksi oleh CTAG. Mesin ini non-semantik.

Ada juga beberapa mesin semantik di YCM. Ada pelengkap berbasis klangd yang keduanya memberikan penyelesaian semantik untuk bahasa C-keluarga. Ada juga pelengkap yang berbasis di Jedi untuk penyelesaian semantik untuk Python, pelengkap berbasis Omnisharp untuk C#, pelengkap berbasis GOPLS untuk GO (menggunakan GOPLS untuk melompat ke definisi), pelengkap berbasis TSServer untuk JavaScript dan TypeScript, server yang berbasis RLS, dan RLS yang berbasis RLS. Lebih banyak akan ditambahkan dengan waktu.

Ada juga mesin penyelesaian lainnya, seperti filepath completer (bagian dari pelengkap pengidentifikasi).

Server akan secara otomatis mendeteksi mesin penyelesaian mana yang akan menjadi yang terbaik dalam situasi apa pun. Kadang -kadang, ini menanyakan beberapa dari mereka sekaligus, menggabungkan output dan menyajikan hasilnya.

Mesin semantik dipicu hanya setelah "pemicu" semantik dimasukkan dalam kode. Jika permintaan yang diterima menunjukkan bahwa kursor pengguna adalah setelah karakter terakhir dalam string foo; foo. Dalam file C#, ini akan memicu mesin semantik untuk memeriksa anggota foo karena . adalah pemicu semantik default untuk C# (pemicu dapat diubah secara dinamis). Jika teksnya string foo; foo.zoo , penyelesaian semantik masih akan dipicu (pemicu di belakang kata zoo yang diketik pengguna) dan hasilnya akan disaring dengan kueri zoo .

Penyelesaian semantik juga dapat dipaksakan dengan mengatur force_semantic: true dalam data JSON untuk permintaan penyelesaian, tetapi Anda hanya boleh melakukan ini jika pengguna secara eksplisit meminta penyelesaian semantik dengan pintasan keyboard ; Jika tidak, serahkan hingga YCMD untuk memutuskan kapan harus menggunakan mesin yang mana.

Alasan mengapa penyelesaian semantik tidak selalu digunakan bahkan jika tersedia adalah karena mesin semantik bisa lambat dan karena sebagian besar waktu, pengguna tidak benar -benar membutuhkan penyelesaian semantik.

Ada dua kasus penggunaan utama untuk penyelesaian kode:

Pengguna tahu nama mana yang mereka cari, mereka hanya tidak ingin mengetik seluruh nama.
Pengguna juga tidak tahu nama yang mereka butuhkan atau tidak yakin apa namanya. Ini juga dikenal sebagai kasus penggunaan "eksplorasi API".

Kasing penggunaan pertama adalah yang paling umum dan secara sepele ditangani dengan mesin penyelesaian pengidentifikasi (yang BTW berkobar cepat). Yang kedua membutuhkan penyelesaian semantik.

Penyaringan string penyelesaian

Hal yang penting untuk dicatat adalah bahwa penyaringan penyelesaian tidak didasarkan pada input menjadi awalan string dari penyelesaian (tetapi itu juga berfungsi). Input harus menjadi kecocokan selanjutnya dari penyelesaian. Ini adalah cara mewah untuk mengatakan bahwa setiap karakter input perlu hadir dalam string penyelesaian dalam urutan di mana mereka muncul dalam input. Jadi abc adalah selanjutnya dari xaybgc , tetapi tidak dari xbyxaxxc .

Peringkat String Penyelesaian

Filter selanjutnya menghapus setiap penyelesaian yang tidak cocok dengan input, tetapi kemudian sistem penyortiran dimulai. Ini sedikit terlibat, tetapi secara kasar berbicara "Word Boundary" (WB) kecocokan karakter selanjutnya adalah "bernilai" lebih dari kecocokan non-WB. Akibatnya, ini berarti diberi input "gua", penyelesaian "getUserAccount" akan diperingkat lebih tinggi dalam daftar daripada penyelesaian "fooguxa" (keduanya merupakan pertandingan berikutnya). Karakter kata-batas adalah semua karakter modal, karakter yang didahului oleh garis bawah dan karakter huruf pertama dalam string penyelesaian.

Shutdown otomatis jika tidak ada permintaan untuk sementara waktu

Jika server belum menerima permintaan apa pun untuk sementara waktu (dikendalikan oleh --idle_suicide_seconds YCMD FLAG), itu akan ditutup dengan sendirinya. Ini berguna untuk kasus -kasus di mana proses yang dimulai YCMD mati tanpa memberi tahu YCMD untuk mati juga atau jika YCMD hang (ini harus sangat jarang).

Jika Anda menerapkan klien untuk YCMD, pastikan bahwa Anda memiliki semacam utas latar belakang yang tidak hidup yang secara berkala mem-ping YCMD (hubungi saja /healthy , meskipun pawang apa pun akan dilakukan).

Anda juga dapat mematikannya dengan melewati --idle_suicide_seconds=0 , meskipun itu tidak disarankan.

Kode keluar

Selama startup, YCMD mencoba memuat perpustakaan ycm_core dan keluar dengan salah satu kode pengembalian berikut jika tidak berhasil:

3: Kesalahan tak terduga saat memuat perpustakaan;
4: Perpustakaan ycm_core tidak ada;
7: Versi perpustakaan ycm_core sudah ketinggalan zaman.
8: Server dimulai dengan Python; kompilasi kembali dengan python3.

Kustomisasi tingkat pengguna

Anda dapat memberikan pengaturan ke YCMD pada startup server. Ada file default_settings.json yang dapat Anda ubah. Lihat bagian Opsi di Panduan Pengguna YCM untuk deskripsi tentang apa yang dilakukan setiap opsi. Lewati jalur ke file pengaturan yang dimodifikasi ke YCMD sebagai --options_file=/path/to/file flag. Perhatikan bahwa Anda harus mengatur pengaturan hmac_secret (menyandikan nilai dengan base64). Karena file yang Anda lewati berisi token rahasia, pastikan Anda membuat file sementara dengan cara yang aman (panggilan sistem Linux mkstemp() adalah ide yang bagus; gunakan sesuatu yang serupa untuk OS lain).

Setelah dimulai, YCMD akan menghapus file pengaturan yang Anda berikan setelah membacanya.

File Pengaturan adalah sesuatu yang harus diproduksi oleh editor Anda berdasarkan nilai yang telah dikonfigurasi oleh pengguna Anda. Ada juga file tambahan ( .ycm_extra_conf.py ) yang seharusnya disediakan pengguna Anda untuk mengkonfigurasi pelengkap semantik tertentu. Informasi lebih lanjut tentang itu juga dapat ditemukan di bagian yang sesuai dari Panduan Pengguna YCM.

`.ycm_extra_conf.py` spesifikasi

Modul .ycm_extra_conf.py dapat menentukan fungsi berikut:

`Settings( **kwargs )`

Fungsi ini memungkinkan pengguna untuk mengkonfigurasi pelengkap bahasa berdasarkan per proyek atau secara global. Saat ini, diperlukan oleh pelengkap berbasis Liblik dan opsional untuk pelengkap lainnya. Argumen berikut dapat diambil dari Kamus kwargs dan umum untuk semua pelengkap:

language : Pengidentifikasi pelengkap yang menyebut fungsi tersebut. Nilainya adalah python untuk pelengkap Python dan cfamily untuk C-Family Completer. Argumen ini berguna untuk mengonfigurasi beberapa pelengkap sekaligus. Misalnya:

 def Settings ( ** kwargs ):
  language = kwargs [ 'language' ]
  if language == 'cfamily' :
    return {
      # Settings for the libclang and clangd-based completer.
    }
  if language == 'python' :
    return {
      # Settings for the Python completer.
    }
  return {}

filename : Jalur absolut dari file yang saat ini diedit.
client_data : Data tambahan apa pun yang disediakan oleh aplikasi klien. Lihat Dokumentasi YouCompleteme sebagai contoh.

Nilai pengembalian adalah kamus yang isinya tergantung pada pelengkap.

Penyelesaikan berbasis LSP

Server LSP sering mendukung konfigurasi pengguna melalui permintaan inisialisasi. Ini biasanya disajikan sebagai opsi di UI. YCMD mendukung ini menggunakan .ycm_extra_conf.py dengan memungkinkan pengguna untuk menentukan kamus pengaturan yang tepat yang dilewatkan dalam pesan inisialisasi server. Opsi -opsi ini dikembalikan dari Settings di bawah kunci ls . Kamus Python dikonversi ke JSON dan termasuk kata demi kata dalam permintaan inisialisasi LSP. Untuk menentukan set opsi untuk server, konsultasikan dengan dokumentasi server atau file package.json . Objek config_sections adalah kamus yang kuncinya adalah "bagian" dan nilainya adalah potongan pengaturan (biasanya ditemukan dalam objek ls ) yang sesuai dengan bagian tersebut. Ini bahkan lebih ditentukan dan membutuhkan coba -coba untuk membuatnya bekerja. Ini opsional dan hanya berguna jika Anda secara eksplisit mengaktifkan dukungan workspace/configuration .

Contoh konfigurasi LSP:

 def Settings ( ** kwargs ):
  if kwargs [ 'language' ] == 'java' :
    return { 'ls' : { 'java.rename.enabled' : False },
             # `config_sections` is not used for java...
             'config_sections' : { 'section0' : {} }

Selain itu, YCMD dapat menggunakan server bahasa apa pun, diberi jenis file dan baris perintah. Opsi Pengguna language_server dapat digunakan untuk mencolokkan server LSP yang biasanya tidak diketahui oleh LSP. Nilainya adalah daftar kamus yang berisi:

name : String yang mewakili nama server
cmdline : Daftar yang mewakili baris perintah untuk menjalankan server (opsional; wajib port tidak ditentukan)
port : Opsional. Jika ditentukan, koneksi TCP digunakan untuk port ini. Jika diatur ke * , port Locall yang tidak digunakan dipilih dan dibuat tersedia di cmdline sebagai ${port} (lihat contoh di bawah).
filetypes : Daftar FileTypes yang Didukung.
project_root_files : Memberitahu YCMD file mana yang menunjukkan root proyek.
capabilities' : Mengesampingkan kemampuan LSP default YCMD.
- Jika Anda mengaktifkan dukungan workspace/configuration , periksa detail conf tambahan, relevan dengan server LSP.
additional_workspace_dirs : Menentukan ruang kerja yang diketahui secara statis yang harus terbuka pada startup server LSP.
triggerCharacters : Mengesampingkan karakter pemicu server LSP untuk diselesaikan. Ini bisa bermanfaat ketika server secara menjengkelkan meminta penyelesaian pada setiap karakter atau misalnya pada karakter whitespace.

{
  "language_server" : [ {
    "name" : " gopls " ,
    "cmdline" : [ " /path/to/gopls " , " -rpc.trace " ],
    "filetypes" : [ " go " ],
    "project_root_files" : [ " go.mod " ],
    "triggerCharacters" : [ " . " ]
  } ]
}

Atau, untuk menggunakan koneksi TCP:

{
  "language_server" : [ {
    "name" : " godot " ,
    "port" : " 6008 " ,
    "filetypes" : [ " gdscript " ]
  } ]
}

Atau, untuk menggunakan port lokal yang tidak digunakan, atur port ke * dan gunakan ${port} di cmdline :

{
  "language_server" : [ {
    "name" : " someserver " ,
    "cmdline" : [ " /path/to/some/server " , " --port " , " ${port} " ],
    "port" : " * " ,
    "filetypes" : [ " somethign " ],
    "project_root_files" : [ " somethingfile " ]
  } ]
}

Saat menyambungkan pelengkap dengan cara ini, kwargs[ 'language' ] akan diatur ke nilai kunci name , yaitu gopls dalam contoh di atas.

Sejumlah pelengkap LSP saat ini didukung tanpa language_server , USCH sebagai:

Jawa
Karat
Pergi
C-keluarga

Seseorang juga dapat mengganti direktori root, dengan project_directory .

 def Settings ( ** kwargs ):
  return { 'project_directory' : 'src/' } # The path may be absolute as well.

Catatan: Jika pelengkap berbasis LSP dikonfigurasi untuk bahasa yang didukung "bawaan", itu menimpa dukungan bawaan.

Pengaturan C-Family

Fungsi Settings disebut oleh liblik dan clangd berbasis pelengkap untuk mendapatkan bendera kompiler untuk digunakan saat menyusun file saat ini. Jalur absolut dari file ini dapat diakses di bawah kunci filename dari Kamus kwargs .

Nilai pengembalian yang diharapkan oleh kedua pelengkap adalah kamus yang berisi item berikut:

flags : (wajib untuk liblik, opsional untuk klangd) Daftar bendera kompiler.
include_paths_relative_to_dir : (opsional) Direktori yang disertakan jalur dalam daftar bendera relatif. Default ke Direktori Kerja YCMD untuk Penyelesaian Liblik dan direktori .ycm_extra_conf.py untuk pelengkap clangd.
do_cache : (opsional) Boolean yang menunjukkan apakah hasil panggilan ini atau tidak (yaitu daftar bendera) harus di -cache untuk nama file ini. Default ke True . Jika tidak yakin, standarnya hampir selalu benar.

Penyelesaian berbasis Liblik juga mendukung item berikut:

override_filename : (opsional) Sebuah string yang menunjukkan nama file untuk parse sebagai unit terjemahan untuk nama file yang disediakan. Fitur yang cukup canggih ini memungkinkan untuk proyek-proyek yang menggunakan build gaya 'Unity', atau untuk file header yang bergantung pada termasuk dalam file lain.
flags_ready : (opsional) Boolean yang menunjukkan bahwa bendera harus digunakan. Default ke True . Jika tidak yakin, standarnya hampir selalu benar.

Contoh minimal yang hanya mengembalikan daftar bendera adalah:

 def Settings ( ** kwargs ):
  return {
    'flags' : [ '-x' , 'c++' ]
  }

Pengaturan pemformatan

Konfigurasi untuk sub -perintah Format dapat ditentukan dengan conf tambahan untuk java subserver dan untuk Subserver TypeScript. Opsi formatter dapat ditemukan di bawah:

Konfigurasi Java
Konfigurasi tsserver,

Server ini mendukung opsi pemformatan khusus untuk disediakan dengan cara yang berbeda dari yang lain. Untuk tujuan ini fungsi Settings dapat mengembalikan properti formatter .

Contoh konfigurasi formatter adalah:

 def Settings ( ** kwargs ):
  return {
    'formatting_options' : {
       'org.eclipse.jdt.core.formatter.lineSplit' : 30 , 
    }
  }

Pengaturan Python

Fungsi Settings memungkinkan pengguna untuk menentukan interpreter Python dan sys.path yang digunakan oleh pelengkap untuk memberikan penyelesaian dan pemahaman kode. Tidak ada argumen tambahan yang disahkan.

Nilai pengembalian yang diharapkan oleh pelengkap adalah kamus yang berisi item berikut:

interpreter_path : (opsional) jalur ke interpreter Python. ~ dan variabel lingkungan di jalur diperluas. Jika bukan jalur absolut, itu akan dicari melalui PATH .
sys_path : (Opsional) Daftar jalur yang dipersiapkan untuk sys.path .

Contoh Penggunaan:

 def Settings ( ** kwargs ):
  return {
    'interpreter_path' : '~/project/virtual_env/bin/python' ,
    'sys_path' : [ '~/project/third_party/module' ]
  }

`PythonSysPath( **kwargs )`

Opsional untuk dukungan Python.

Fungsi ini memungkinkan kustomisasi lebih lanjut dari python path sys.path . Parameternya adalah item yang mungkin dikembalikan oleh fungsi Settings untuk Python Completer:

interpreter_path : Jalur ke interpreter Python.
sys_path : Daftar jalur Python dari sys.path .

Nilai pengembalian harus menjadi daftar jalur Python yang dimodifikasi.

Lihat sendiri .ycm_extra_conf.py untuk contoh.

Spesifikasi File Ekstra Global Ekstra

Modul ekstra global harus mengekspos fungsi yang sama dengan modul .ycm_extra_conf.py dengan penambahan berikut:

`YcmCorePreLoad()`

Opsional.

Metode ini, jika didefinisikan, dipanggil oleh server sebelum mengimpor plugin C ++ Python. Biasanya tidak diperlukan dan penggunaannya hanya untuk pengguna tingkat lanjut.

`Shutdown()`

Opsional.

Dipanggil sebelum server keluar dengan bersih. Biasanya tidak diperlukan dan penggunaannya hanya untuk pengguna tingkat lanjut.

Kompatibilitas ke belakang

Antarmuka HTTP+JSON YCMD mengikuti SEMVER. Sementara YCMD telah melihat penggunaan ekstensif selama beberapa tahun terakhir sebagai bagian dari YCM, nomor versi di bawah 1,0 karena beberapa bagian API mungkin sedikit berubah karena orang menemukan kemungkinan masalah mengintegrasikan YCMD dengan editor lain. Dengan kata lain, API saat ini mungkin secara tidak sengaja spesifik. Kami tidak menginginkan itu.

Perhatikan bahwa API internal YCMD (yaitu apa pun selain http+json) tidak ditanggung oleh SEMVER dan akan berubah secara acak di bawah Anda. Jangan berinteraksi dengan kode Python/C ++/ETC secara langsung!

FAQ

Apakah HMAC Auth untuk permintaan/tanggapan benar -benar diperlukan?

Tanpa Auth HMAC, mungkin bagi situs web jahat untuk menyamar sebagai pengguna. Jangan lupa bahwa Evil.com dapat mengirim permintaan ke server mendengarkan di LocalHost jika pengguna mengunjungi Evil.com di browser.

Ini bukan hanya masalah teoretis ; Eksploitasi Eksekusi Kode Jarak Jauh Bukti-Konsep Kerja dibuat untuk YCMD yang berjalan di LocalHost. Auth HMAC ditambahkan untuk memblokir vektor serangan ini.

Kode Etik Kontributor

Harap dicatat bahwa proyek ini dirilis dengan kode perilaku kontributor. Dengan berpartisipasi dalam proyek ini, Anda setuju untuk mematuhi persyaratannya.