Visual Studio Code Extension: MacGyver gibi Düşün!

Bu yazıya çözümlerin ve ihtimallerin limitsiz olduğu bir dünyaya inanmamı sağlayan MacGyver’a teşekkür ederek başlamak istiyorum. Koca yürekli, garip saçlı, karıncadan roketatar yapabilecek kadar yetenekli adam.

Despite no gadgets, there was this guy… named MacGyver who could do it all!

Hem giriş yaparken hafif bir sohbet olmuş olsun, hem de bilmeyenlere ufak bir bilgilendirme; MacGyver 1985'lerde çıkmış ama bizim ülkemize gelişi ve tekrarları benim çocukluğuma denk gelen bir dizi. Şimdilerde bir devam dizisi çekiliyor sanırım. Çeşitli gereksinimlerini kendi kendine karşılayabilen zat, ihtiyaç duyduğu aletleri yaparak başlayan ve üretmek istediği ürünlere temelden girebilen biri.

Üretmek, ihtiyaçlar, alet edevat, plug-in, extension ve Visual Studio Code, sanırım derdimi anlatabildim 😂.

“Well, when it comes down to me against a situation, I don’t like the situation to win.” — MacGyver

Benim bu makalede anlatacağım şey ise, buna göre çok daha basit ama aynı yolda onun yaktığı ışıkta ilerleyen bir örnek olacak.

Bir süredir editor olarak Visual Studio Code kullanıyorum. Neredeyse 50 den fazla editor kullanmışımdır. Bunlardan bazıları kod, bazıları doküman için oldu ama sadece 2 tanesi için genişleme paketi yazdım; Eclipse ve VSC. Eclipse ile tanıştığımda üniversitedeydim, VSC ise hayatıma soğuk bir 2016 sonbahar akşamında girdi. Eclipse anılarım kan ve vahşet içerdiği için bugün sadece geliştirdiğim VSC eklentisinden bahsedeceğim: crates.

Kolları Sıvama Vakti

“If you don’t have the right equipment for the job, you just have to make it yourself.” — MacGyver (Out in the Cold)

İlk olarak kodları şuracığa bırakayım ve uyarayım, kodlar güncellendikçe makale geri kalacaktır 😞.

Gereksiz bir sürü bilgiye uzun uzun vakit ayırdıktan sonra artık neden extension yazma işine girdiğimi anlatabilirim 😀 . Rust yeni sayılabilecek bir programlama dili. Genelde VSC’yi Rust ve JS/TS (node’lu, webpack’li olanı) kodlarken kullanıyorum. NPM kullananlar bilir JS/TS yazarken genellikle package.jsonkullanarak bağımlılıkları yönetiriz.

Kullandığımız bağımlılıkların hangi versionları var?

Bizdeki son sürüm mü ?

Aklımda deli sorular…

Bağımlılıkları yönetmenin daha kolay olabilmesi için kullandığım Version Lens adlı çok sevdiğim bir eklenti var ve aynısını Rust için yapmaya karar verdim.

Genel olarak Version Lens ve diğer bağımlılık yönetim araçlarında yapılan şey şu;

1. Bağımlılıkların tanımlandığı dosyayı parse et.
2. Merkezi repository içerisinde hangi versionları var kontrol et.
3. Aldığın cevaplara göre geliştiriciye görsel bildirim ve kolay yönetme imkanı sağla.

Rust olmak zorunda değil. Bu örneği takip ederek başka diller içinde benzeri eklentiler yazabilirsiniz.

Öncelikle bilgisayarınızda 2 adet kurulu olması gereken program var.

• Node & Npm
• VSC

Bunlar hazırsa VSC için geliştirme ortamını kurarak başlayalım. Dokümanlarından adım adım gideceğim.

Kolay kurulum yapabilmemiz için bir Yeoman kullanarak proje oluşturucu yazılmış. Kurulu değil ise aşağıdaki komut ile global olarak kurabiliriz.

npm install -g yo generator-code

Yeoman kurulduktan sonra projemizi yaratmaya başlayabiliriz. Çeşitli sorularla extension geliştirme ortamımızı ayarlamaya başlıyor. Sırası ile yaptıklarım aşağıdaki videoda var. Benim projemin ismi crates, siz istediğiniz ismi verebilirsiniz.

npm install biraz zaman alabilir. İşlemler bittiğinde elinizde geliştirilmeye hazır bir proje iskeleti olacak. Şimdi oluşan projeyi açalım ve ilk test sürüşümüzü yapalım. Projeyi açtığımızda bizi karşılayan ekran aşağıdaki gibi olacak.

Debug tabında Run komutuna tıkladığımızda aşağıdaki ekran görüntüsündeki gibi yeni bir VSC instance’ı açılacak ve yeni geliştirdiğimiz eklentimiz kurulu olarak gelecek.

Bu adıma kadar sorunsuz gelebildiyseniz proje ayarlarınızda hiçbir sıkıntı yok demektir.

Oluşturulan proje basit bir HelloWorld commandı tanımlıyor. Hemen test edebilriz.

Artık değişikliklerimizi yaparak, yavaş yavaş hedefimize doğru ilerleyelim. Şimdi öncelikle extension’un ne zaman aktive edileceğini VSC ye belirteceğiz. Bunun için package.json içerisinde activationEvents alanı kullanılıyor.

Şu an belirtildiği üzere extension sayHello komuyu çalıştırıldığında aktive oluyor. Bizim ihtiyacımız ise bağımlılıkları yönetmek istediğimiz bir durum ortaya çıkarsa aktive olmak. Birkaç yöntem denedikten sonra en iyi çözümün Cargo.toml dosyasının varlığını kontrol etmek olduğu sonucuna vardım.

Cargo.toml : Rust projelerinde bağımlılıkları yönetmek için kullanılan package.json benzeri bir dosya.

// Bu kısmı
"activationEvents": [
        "onCommand:extension.sayHello"
 ],

// Şu şekilde değiştirelim.
"activationEvents": [
  "workspaceContains:Cargo.toml"
],

activationEvents ne değerler alabilir? Detaylarını merak ederseniz dokümanlarında çok güzel anlatmış. Artık istediğimiz zaman aktive olmasını sağlayabildiğimize göre şimdi sıra ufak bir test yapmakta. Bunun için çok basit bir listener yazacağız ve doğru zamanda bildirip tetikliyor mu kontrol edeceğiz. Sizden ricam açılacak VSC yi rahat bir şekilde test edebilmek için herhangi bir klasör içine Cargo.toml diye bir dosya oluşturup o klasörü VSC ile açın. Içeriğinin dolu olmasına gerek yok.

samplefolder/
├── Cargo.toml
├── otherfile.rs

/*extensions.ts*/
'use strict';
import { window, ExtensionContext,TextEditor}  from 'vscode';

export function activate(context: ExtensionContext) {
    // Aktif olunduğunda bildir.
    window.showInformationMessage('Congratulations, your extension "crates" is now active!');

    const listener = (editor: TextEditor | undefined): void => {
        window.showInformationMessage('Cargo.toml!!!!!');
    };
    //Text Editor değiştiğinde tetikle
    context.subscriptions.push(window.onDidChangeActiveTextEditor(listener));
}

export function deactivate() {
}

Tekrardan çalıştırıp açılan VSC ile örnek klasörünüzü açın (File → Open → samplefolder). Doğru şekilde klasörü açıp explorerdan Cargo.toml dosyasını seçtiğinizde göreceksiniz, 2 adet bildirim gelecek. Bunlardan ilki eklentinizin aktive olduğunu belirtiyor. Eğer VSC ile açtığınız klasörün içinde Cargo.toml varsa, eklenti aktive olduğu için ilk göreceğiniz bildirim bu olacaktır. Sonrasında aktif dosya editör seçiminiz değiştikçe diğer bildirimin tetiklendiğini göreceksiniz.

Her değişimde tetiklenecek ama bizim istediğimiz sadece hedef dosya açıldığında tetiklenmesi. Bunun nedeni, sadece aktif editöre bir dinleyici eklememiz ve başka bir kontrol yapmamamız. Bunu önlemek için dosya adına göre bir kontrol eklememiz iyi olacaktır.

/*extensions.ts*/
'use strict';
import { window, ExtensionContext,TextEditor}  from 'vscode';

export function activate(context: ExtensionContext) {
    window.showInformationMessage('Congratulations, your extension "crates" is now active!');

    const listener = (editor: TextEditor | undefined): void => {
         if (editor) {
            const { fileName } = editor.document;
/*====>*/   if (fileName.toLocaleLowerCase().endsWith("cargo.toml")) {
                window.showInformationMessage('Cargo.toml!!!!!');
            }
         }
    };
    context.subscriptions.push(window.onDidChangeActiveTextEditor(listener));
}

export function deactivate() {
}

“The great thing about a map: it gets you in and out of places in a lot different ways.” — MacGyver (The Gauntlet)

Kodları düzenli tutmak adına oluşturduğum klasör yapısını sizinle ağaç olarak aşağıda paylaşıyorum. Genel resmi görmek adına yararlı olacağını düşünüyorum.

./src/
├── api
│   └── index.ts          # Bağlanılacak adresi ve yardımcı kodları tutan dosya
├── extension.ts          # Bütün hayatın başladığı dosya. 
├── test
│   ├── extension.test.ts # eksik testler :D
│   └── index.ts
├── toml
│   ├── commands.ts           # toml'da version değişikliğini yapacak command
│   ├── decorations.ts        # versiyonları hover'ı açmak için dekorasyon    
│   └── listener.ts           # Cargo.toml dosyalarını filtreleyen listener
└── ui
    ├── decorations.ts        # ortak dekorasyonlar
    └── indicators.ts     # status bar işlemleri için yardımcı obje

Önceden de dediğim gibi kodlar geliştikçe makale eskiyecektir. Bu uyarıyla beraber tekrar hatırlatayım, kaynak kodlara buradan ulaşabilirsiniz. Kod işin ilk kısmıydı, şimdi ise extension geliştirmeyi tamamlamak için gereken diğer işlemleri anlatacağım.

“Typical. Just when you’re getting ahead, someone changes the odds.” — MacGyver (Pegasus)

Dünyaya Açılalım

Bu kısımda yazdığımız eklentiyi markette yayınlamak için gerekli işlemler hakkında ufak bir bilgilendirme yapacağım. Umarım ilk kısımda gösterilenler işinize yaramıştır ve işin ana hatları konusunda bir bilgi verebilmiştir. Yapılabileceklerin bir limiti yok ama kapsamı küçük başlatıp bir an önce markete çıkmak gerekli. Ürünün gideceği yöne, kulllananlar karar verecek 😊. Markete çıkmadan önce yapılacak ve dikkat edilecek bazı noktalar var, bunlardan bahsetmek istiyorum. Yine daha detaylı bilgi için dokümanlara bakmanızı tavsiye ederim.

1. Market package.json içindeki bilgilere bağlı çalışıyor. İsim, repo, version gibi bilgileri güzel doldurmaya dikkat edin. Ayrıca eklenti için gösterilecek olan icon yine burada belirtilecek.
2. Market üzerinde README.md direkt ana sayfa şeklinde açılacak. Güzel bir açıklama ve geliştirilen eklenti hakkında bilgilendirme yapmaya çalışın. Yine CHANGELOG.md dosyası üzerinde versiyon değişikliklerinizi güzelce anlatın ki insanlar yeni özellikler neler anlayabilsin.
3. vsce bir komut satırı uygulaması ve eklentinizi markete çıkmak için gerekli işlemleri yapmanıza yardımcı oluyor. Global olarak yüklemenizi tavsiye ederim.

npm install -g vsce

1. Personal Access Token almanız gerekli. Buradan ücretsiz bir hesap açarak ve buradaki adımları gerçekleştirerek bir token alabilirsiniz. Bu token ile makinanızda kendinizi yayıncı olarak tanımlayacaksınız ve yayınladığınız eklentiler sizinle eşleşecek. Token aldıktan sonra yayıncı yaratıp token ekleyin.

vsce create-publisher (publisher name)
   vsce login (publisher name)

Pete: Are you sure this is going to work?!

MacGyver: Nope.

Tebrikler artık vsce publish ile eklentinizi markete yollayabilirsiniz.

Çok detaya girmeden örnek vererek, eklenti geliştirebilmek için gerekli temel bilgileri paylaşmaya çalıştım. En azından uğraşmak istediğiniz bir şey olup olmadığına karar vermenize yardımcı olabileceğini düşünüyorum.

“İyi de ben şimdi ne yapacağım?” diyor olabilirsiniz. Sık yaşadığınız bir sorunu çözmeye çalışın. Kesinlikle sizi tekrar tekrar uğraştıran bir iş vardır. Devamını isterseniz haber vermekten çekinmeyin 🎉.

Sevgiler…