Referans44 dk okuma
collage CLI
collage CLI'ın new, add ve dev'den plugin, ai, completion ve man'e kadar bütün komutları, flag'leri ve her birinin neyi çalıştırdığı.
collage komutu yeni projeleri scaffold eder ve var olan projelerinizi yönetir. Bir projeyi development modunda çalıştırır, deploy edeceğiniz binary'yi derler ve projeyi static dosyalar olarak export eder.
go install github.com/Elagoht/collage/cmd/collage@latest
CLI, uygulamanızı kendi içine asla link etmez. Zaten edemez de, çünkü uygulamanız sizin kodunuzdur. dev, build, export, inspect ve check komutları, go aracını bulunduğunuz dizinde tıpkı elle çalıştıracağınız gibi çalıştırır. Bu sayfanın geri kalanı her komutun tam olarak neyi çalıştırdığını anlatır.
Kullanım
collage <command> [flags]
| Komut | Ne yapar |
|---|---|
new | Yeni bir collage projesi scaffold eder |
add | Bulunduğunuz projeye bir page, fragment, action, document, layout, guard, middleware ya da command yazar |
dev | Bulunduğunuz dizindeki projeyi development modunda çalıştırır |
build | Bulunduğunuz dizindeki projeyi deploy edeceğiniz binary'ye derler |
export | Bulunduğunuz dizindeki projeyi static dosyalara render eder |
serve | Bir static export'u, bir static host'un sunacağı şekilde sunar |
routes | Bulunduğunuz dizindeki projenin cevap verdiği her URL'yi, her birinin karşılaştığı guard'larla listeler |
inspect | Bulunduğunuz dizindeki projenin nelerden oluştuğunu JSON olarak yazdırır |
check | Bulunduğunuz dizindeki projenin template'lerini render etmeden kontrol eder |
plugin | Projeye plugin ekler, çıkarır ya da bir plugin repository'sini kontrol eder |
ai | Projenin coding agent'lar için kurallarını içeren AGENTS.md'yi yazar ya da günceller |
completion | bash, zsh ya da fish için bir shell completion script'i yazdırır |
man | collage'ın man sayfasını yazdırır ya da man'in bulacağı yere kurar |
version | collage CLI'ın sürümünü yazdırır |
help | Bir komutun yardımını gösterir ya da bütün komutları listeler |
collage help <command> o komutun kendi kullanım bilgisini yazdırır. collage <command> -h de aynı şeyi yapar. Flag'ler Go'nun flag sözdizimini kullanır: -out dist ile -out=dist aynıdır, --out da çalışır.
Yanlış yazılmış bir ad, hatasının sonunda en yakın geçerli adı önerir:
collage: unknown command: "chek" (did you mean "check"?)
Bu, CLI'ın geçerli değerlerini bildiği her ad için böyledir: bir komut, bir alt komut, bir add türü, bir flag, bir --template, bir @bundle ve bir plugin. Plugin, plugin add için bir paketin adını verdiği, plugin del için ise plugins.go'da bulunan plugin'dir. Hiçbirine yakın olmayan bir ad yalnızca hatayı alır; çıkış kodu her iki durumda da aynıdır.
collage new projeyi bir kez scaffold eder. Proje üzerinde çalışırken add, dev, check, plugin add ile del ve inspect, bulunduğunuz dizindeki projeye etki eder. Yayına almak için collage build bir sunucu için tek bir binary derler; binary HOST ve PORT üzerinde dinler. -i ise yanına bir image dosyası ve bir servis unit'i yazar. Ya da collage export projeyi dist/ içine render eder; collage serve, siz yüklemeden önce dist/'i bir static host'un sunacağı gibi gösterir. collage plugin check şemada yoktur: bir plugin'in kendi repository'sinde çalışır.Çıkış kodları
| Kod | Anlamı |
|---|---|
0 | Başarılı. help, collage -h ve collage <command> -h de bu kodla çıkar |
1 | Komut doğru parse edildi ama işini yapamadı |
2 | Kullanım hatası: komut verilmedi, komut bilinmiyor, flag hatalı ya da beklenmeyen bir argüman var |
collage new
collage new <name> [--template minimal|demo] [--with plugins] [--dir path] [--module path] [--force] [--ai]
<name> adında, çalıştırılmaya hazır yeni bir proje scaffold eder.
| Flag | Varsayılan | Anlamı |
|---|---|---|
--template name | minimal | Scaffold edilecek proje: minimal ya da demo |
--with plugins | yok | Proje yazıldıktan sonra eklenecek plugin'ler: @prod gibi paketler ve elagoht/session gibi plugin'ler, virgülle ayrılmış ya da birden fazla --with ile |
-dir path | ./<name> | Projenin scaffold edileceği dizin |
-module path | <name> | go.mod'a yazılan module path |
-force | kapalı | Dizin boş olmasa da scaffold eder |
--ai | kapalı | Coding agent'lar için kuralları içeren AGENTS.md'yi ve onu import eden bir CLAUDE.md'yi collage ai init gibi yazar |
collage new myblog # into ./myblog, module "myblog", one page
collage new myblog --template demo # the demos and their tests
collage new myblog -module github.com/me/myblog
collage new . # bulunduğunuz dizine, onun adıyla
collage new myblog -dir . -force # into the current, non-empty directory
collage new myblog --with @blog,@prod # iki paketin plugin'leriyle birlikte
collage new myblog --ai # and AGENTS.md for coding agents
--with, hiçbir şey yazılmadan önce okunur: var olmayan bir paket ya da okunamayan bir plugin adı kullanım hatasıdır ve dizin oluşturulmaz. Proje scaffold edildikten sonra new, projeye CLI'ın kendi collage sürümünü ekler, ardından her plugin'i collage plugin add gibi ekler. Başarısız olan plugin raporlanır ve dışarıda bırakılır; proje ve diğer plugin'ler kalır, komut 1 ile çıkar. Eklenen her plugin'in sizden beklediği şeyler (setup notu, template fonksiyonları ve dokümantasyonu) en sonda, bir arada yazdırılır.
Scaffold edilen main.go, BASE_URL'ü Config.BaseURL'e okur: sitemap'in, canonical link'in ya da feed'in bir path'in önüne koyduğu origin. Bunu yazan bir plugin eklenene kadar boş kalabilir.
Flag'leri tek ya da çift tireyle yazabilirsiniz. Flag'ler addan önce de sonra da gelebilir. Tam olarak bir ad vermeniz gerekir. Hiç ad vermemek ya da birden fazla ad vermek kullanım hatasıdır.
<name> projenin adıdır ve --module başka bir şey demedikçe module path'idir de; bu yüzden geçerli bir module path olmalıdır: go mod init'in kabul ettiği gibi harfler, rakamlar ve - . _ ~, / ile ayrılmış parçalar hâlinde; hiçbir parça boş olamaz, nokta ile başlayamaz ya da bitemez. Argüman olarak bir path (en başta .) verirseniz proje oraya scaffold edilir ve adını o dizinden alır; my site gibi bir dizine module path vermenin yolu --module'dür. --dir ile birlikte argüman yalnızca bir addır, path olamaz. Geçerli bir module path olmayan bir ad ya da --module, hiçbir şey yazılmadan önce 2 çıkış koduyla reddedilir.
Hedef dizin varsa ve boş değilse, -force vermediğiniz sürece komut reddedilir. -force verdiğinizde ise scaffold'un yazdığı dosyalar, dizindeki aynı adlı dosyaların yerine geçer ve komut bu dosyaları sayar: aralarındaki go.mod, sizin module path'iniz ve dependency'lerinizdir. Bulunduğunuz dizine scaffold ettiğinizde sonraki adımlarda cd yer almaz.
Scaffold edilen go.mod, collage'ın derlendiği en eski Go olan Go 1.26.11'i ister.
Her projede şunlar bulunur:
go.mod;- elli satır kadar bir
main.go: kendisine verilencollage.Env'den config'i ve static mount'u kurannewAppile onucollage.Main'e veren birmain.collage.Main, aşağıda anlatılan CLI sözleşmesini yerine getirir ve plugin komutlarını dispatch eder; files'ı tanımlayanembed.goveembed_dev.go: template'ler, static dosyalar veplugins-config.jsonembed edilir, development build'inde ise proje dizininin kendisi kullanılır (bkz. aşağısı);- boş bir
plugins.goileplugins-config.jsonve bir.env.example; - bütün route'ları register eden bir
routes.go; - sitenin adını
WithTitleile veren ve hiç slot tanımlamayan bir layout (böylece bir page'in kendi başlığı sitenin başlığının yerine geçer); - markup'ı Go dosyasında inline duran ve proje adını
collage.Valueile alan bir ana sayfa (içinde hiçbir şey veri çekmediği içinStatic()demeden static'tir); static/, bir.gitignoreve bir README.
.env.example'ı collage dev'in, go run .'un ve derlenmiş binary'nin okuduğu .env'e kopyalayın; --template demo ile komutun yazdırdığı sonraki adımlar da bunu söyler.
--template demo, projeye canlı demolardan oluşan bir page ekler: JSON dönen bir action, kendi page'ine post eden bir form, kendi URL'si olan bir fragment ve bir JSON document. Demo projesi ayrıca bir not-found page'i, collagetest ile yazılmış, her biri için testleri ve bir favicon'u da ekler.
Yerleşim alana göredir, yani gerçek bir uygulamanın yerleşimidir:
pages/<area>/<name>.go a page: its layouts, content, path, actions
fragments/layouts/master.go Master(), the layout every page wraps itself in
fragments/pages/<area>/<name>.go each page's content, mirroring pages/
actions/<area>/<name>.go an action and its handler, one per file
documents/<name>.go routes that are not HTML
data/<domain>/ state, by domain
templates/layouts/ the layouts' HTML
pages/ ve fragments/pages/ alan alan birbirini yansıtır. İçlerindeki her package'ın adı pages ya da fragments'tır. Bu yüzden bir page dosyası kendi içeriğini fragments "<module>/fragments/pages/<area>" olarak import eder; routes.go da her alanın page'lerini demopages gibi bir alias ile import eder. Page'ler ve fragment'lar markup'larını inline tutar: data handler'larının yanında bir collage.InlineHTML const'u olarak. Markup'ını templates/layouts/ içinde tutan yalnızca layout'lardır. Bir page'in markup'ını düzenlemek bir Go değişikliğidir ve collage dev bunun için yeniden build alır. Layout'un <head>'inde {{hoist "head"}} sitenin stylesheet'inden sonra gelir. Böylece bir fragment'in hoist ettiği stylesheet, eşit specificity'de sitenin stylesheet'ine üstün gelir. Bir page'in WithActionFor ile eklediği bir action, page'le aynı adı taşır ve kendine ait bir path'i yoktur. routes.go her şeyi tek bir app.Register çağrısıyla register eder.
Minimal proje varsayılan projedir ve bir projenin olabileceği en yalın hâldir. İçinde tek bir page'i saran layout vardır. Bu page <h1>Hello from {{.Name}}</h1> satırından ibarettir; {{.Name}}, template'e collage.Value ile verilen proje adıdır. Bunun yanında arka plan ve metin rengini dark mode dahil ayarlayan bir stylesheet bulunur. Başka hiçbir şey yoktur: test yoktur, not-found page'i de yoktur. Siz bir not-found page'i register edene kadar collage bilinmeyen adreslere kendi sade 404'üyle cevap verir.
İş bittiğinde sonraki adımları yazdırır:
cd myblog
go mod tidy
collage dev
collage add
collage add <kind> <[area/]name> [flags]
Scaffold'un yerleşimine uygun bir page, fragment, action ya da document yazar ve onu routes.go içinde register eder. Bir layout, bir guard, bir middleware ya da bir command da yazar:
collage add page blog/post # pages/blog/post.go + fragments/pages/blog/post.go
collage add page blog/post --file # its template in templates/pages/blog/post.html
collage add fragment blog/sidebar # fragments/blog/sidebar.go, for a slot
collage add fragment layouts/partials/siteFooter --file
# fragments/layouts/partials/siteFooter.go
# + templates/layouts/partials/siteFooter.html
collage add action blog/comment # actions/blog/comment.go, the action and its handler
collage add action blog/ping --path /api/ping
collage add document feed --path /feed.xml --type application/xml
collage add action blog/like --page blog/post # attached to pages/blog/post.go
collage add layout panel # fragments/layouts/panel.go, nested
collage add guard admin # guards/admin.go, yalnızca guard fonksiyonu
collage add layout panel --guard admin # onu taşıyan bir layout
collage add page admin/users --layout panel
collage add page login --guard guest # page'in içeriğine WithGuard
collage add middleware loadUser # middleware/loadUser.go + app.Use in routes.go
collage add command seed # commands/seed.go + app.RegisterCommand
| Flag | Varsayılan | Anlamı |
|---|---|---|
--file | kapalı | Template'i inline değil, template kökü altındaki bir dosyada tutar |
--path pattern | /<area>/<name> | URL. Path'i olmayan bir action, eklendiği page'de cevap verir |
--name name | son parça | Page'in, action'ın, document'ın ya da command'ın adı |
--locale code | Locale.Default ya da en | Path'in ait olduğu locale |
--type type | text/plain; charset=utf-8 | Bir document'ın content type'ı |
--layout name | yok | Bir page'in layout'u: add layout <name>'in yazdığı layout, sitenin layout'unun içinde |
--guard name | yok | add guard <name>'in yazdığı guard ile .WithGuard(guards.<Name>): bir page'in içeriğinde, bir layout'ta ya da bir action'da |
--page target | yok | Bir action'ın page'i, [area/]name: action'ı o page'e ekler |
--dir path | . | Proje |
- Bir page,
layouts.Master()ile (ya dafragments/layoutsiçinde argüman almayan ilk layout ile) sarılmış birpages/<area>/<name>.godosyasıdır. İçeriğifragments/pages/<area>/<name>.goiçindedir: bir template, bir view struct'ı ve page'in başlığını belirten, tipli bircollage.Loadhandler'ı. Handler'ı, içeriğin fonksiyonunun çağırdığı<name>Data() collage.Dataüretir. Bu yüzden handler'ın ihtiyaç duyduğu bir servis, ikisine eklenen bir parametredir; bkz. Data handler'lar. - Bir action,
actions/<area>/<name>.godosyasıdır. Page'ler gibi her dosyada bir tane bulunur: önce builder'ı, altında da handler'ı. Handler,<name>Handler()adında bir factory'dir; fragment'ın data handler'ı gibi, bu sayede ihtiyaç duyduğu bir servis tek bir parametre uzağındadır. Paketin adıactions'tır ve bir alanın page'lerinin<area>pagesolması gibi<area>actions(blogactions) adıyla import edilir. Alanı olmayan bir actionactions/<name>.godosyasıdır. Zatenactions/<area>.godosyalarında ya daactions/funcs/içinde duran action'lara dokunulmaz; yenileri onların yanına, klasörlere yazılır.--pathverildiğinde action kendine ait bir URL'de cevap verir ve register edilir. Verilmediğinde ise eklendiği page'de cevap verir ve komut, eklemeniz gereken.WithActionFor(...)satırını yazdırır. --page <[area/]name>, yeni action'ı nasıl ekleyeceğinizi yazdırmak yerine onu o page'e kendisi ekler: page'inNewPagezincirini bitirenBuild()'den önce.WithActionFor(blogactions.Like())satırını koyar ve action'ın paketini import eder. Birden fazla zincir içeren bir page dosyasına dokunmaz, eklenecek satırı yazdırır.--pathile birlikte verilemez.- Bir document,
documents/<name>.godosyasıdır. - Bir layout, sitenin kendi layout'unun içine yerleşip page'in içeriğini saran bir layout'tur:
fragments/layouts/<name>.go, içinde<div class="<name>">{{slot "content"}}</div>. Template'i inline olur,--fileile bir dosyada durur.--layout <name>yeni bir page'i onunla sarar,--guard <name>ise layout'a o guard'ı verir.add layout'un yazdığı layout'lar//collage:nestedile işaretlenir, guard taşıyan bir layout da iç içe sayılır: bunların hiçbiri, yeni bir page'in içine konduğu site layout'u sanılmaz. - Bir guard yalnızca
guards/<name>.godosyasıdır, guard fonksiyonunun kendisi: siz kontrolünü yazana kadar herkesi403ile reddeden birGuardFunc. Bir request'i geçirmek içinnil, nil, başka yere göndermek için bir redirect dönün.--guard <name>onu sorulacağı yere koyar: yalnızca.WithGuard(guards.Admin)ekler, başka bir şey değil. Guard'ın var olması gerekir, yoksa komut önce çalıştırılacakadd guard'ı söyleyerek reddedilir.add page'de guard, page'in içerik fragment'ine konur (page builder'ın kendi guard'ı yoktur); page'in render'ları, ona eklenmiş action'lar ve fragment path'leri ona sorulur.add layout'ta guard layout'a konur ve onunla sarılan her page önce guard'a sorulur. Kendi--path'i olan bir action'ın page'i yoktur;add action ... --guard adminguard'ı ona doğrudan verir. - Bir middleware, her request'i bir sonrakine geçiren bir
func(http.Handler) http.Handlerolanmiddleware/<name>.godosyasıdır.app.Useile, zaten var olan middleware'lerden sonra register edilir; ilk register edilen en dıştadır. Routing'den önce çalışır, guard'lar ise ondan sonra. Bu yüzden bir guard, middleware'in request context'ine koyduğunu okuyabilir: giriş yapmış kullanıcıyı middleware'de yükleyin, kararı guard'da verin. - Bir command,
app.RegisterCommandile register edilen bircollage.Commandolancommands/<name>.godosyasıdır:go run . <name>ya da build edilmiş binary'nin ardından bu ad, sunucu yerine onu çalıştırır.--nameona Go adı olmayan bir ad verir, örneğinuser-add. Projede başka bircollage.Command'ın kullandığı bir ad reddedilir;RegisterCommand'ın reddettiği gibi, tek bir shell kelimesi olmayan bir ad da. Bir service'e ihtiyacı olan middleware ya da command, onu sizin ekleyeceğiniz bir argüman olarak alır. İkisi de register fonksiyonuna kendi satırı olarak eklenir:if err := app.Use(...); err != nil { return err }. Bunun için fonksiyonun*collage.Appalması veerrordönmesi gerekir; değilse eklenecek satır yazdırılır. - Bir fragment, bir page'in ya da layout'un bir slot'u için page'i olmayan bir page içeriğidir. Komut, onu bağlayan
.WithSlotFragment(...)satırını yazdırır. Path'inin gösterdiği yere,fragments/<area>/<name>.go'ya yazılır; template'i de template kökü altında<area>/<name>'dedir. Package'ı o dizinde zaten olan package'tır, yoksa dizinin adını alır:fragments/layouts/partials,partialsolur. Bir page'in içeriğinin yanında duracak bir fragmentcollage add fragment pages/blog/relatedile yazılır.
Son parça bir Go adıdır ve yazıldığı gibi kalır: blog/storyDetail, layouts/partials/siteFooter. --name başka bir ad vermedikçe komutun yazdığı her şey, yani dosya, varsayılan URL ve ad, bu parçanın adını alır. Böylece blog/storyDetail, /blog/storyDetail adresindeki "storyDetail" page'idir. Fonksiyonu da ilk harfi büyütülmüş aynı addır: StoryDetail(). Tireli bir ad Go adı olmadığı için reddedilir. Son parçadan önceki dizinler yalnızca bir path'tir ve tire içerebilir: user-settings/profile. Package'ları ve import alias'ları tireleri atar: usersettings. Package adı bir Go keyword'ü (type), main, init ya da Go'nun önceden tanımladığı bir ad (string, error, len) olacak bir alan, nasıl yazılmış olursa olsun (Type de) reddedilir: ilk üçü başka bir dosyanın import edebileceği bir package olamaz, sonuncusu ise onu import eden her dosyada yerleşik adı gölgeler. Path'in locale'i, main.go onu nasıl yazıyorsa Locale.Default'tur; orada bir literal değilse en'dir; ya da --locale ile verilendir. Bir template dosyası Template.Root altına, Extension'ıyla birlikte yazılır; bunlar da aynı şekilde okunur. Komut hangi locale'i kullandığını söyler.
Komut, routes.go'nun zaten tuttuğu listeye register eder. Bu liste bir app.Register(...) çağrısı olabilir; yeni öğe kendi türündeki son öğeden sonra gelir. Ya da RegisterPage ile üzerinde dolaşılan bir []*collage.Page{...} literal'i olabilir; Document ve Action için de aynısı geçerlidir. Komut dosyayı yerinde düzenler, böylece yorumlar oldukları yerde kalır. Alanın package'ını da scaffold'un kullandığı türden bir alias ile import eder. Böyle bir liste yoksa orada hiçbir şeyi değiştirmez ve eklenmesi gereken satırı yazdırır. Constructor'lar argüman almaz: bir servise ihtiyaç duyan bir page'e o servis elle eklenir.
Hiçbir şeyin üzerine yazılmaz. Hiçbir şey yazılmadan önce her şey hesaplanır. Var olan bir dosya, projenin zaten tanımladığı bir page, action ya da document adı ya da bir dosyanın gireceği package'da zaten bulunan bir identifier, komutu hiçbir şey yazmadan durdurur.
collage dev
collage dev
Bulunduğunuz dizindeki projeyi build eder ve COLLAGE_DEV=1 ayarlanmış olarak çalıştırır. Go kodu ya da plugins-config.json her değiştiğinde projeyi yeniden build edip yeniden başlatır. Hiçbir flag ya da argüman almaz. Durdurmak için Ctrl-C'ye basın. Interrupt sinyali programa da ulaşır ve program production'da nasıl kapanıyorsa öyle kapanır. Bir SIGTERM ya da kapanan bir terminalin gönderdiği SIGHUP da onu aynı şekilde durdurur: program kapatılır ve geçici build dizini silinir.
Tarayıcı programla değil, collage dev ile konuşur. collage dev, programınızın okuyacağı şekilde HOST ve PORT üzerinde dinler (varsayılan olarak localhost:6060). Her request'i programa iletir. Programı ise HOST ve PORT'u kendine ait bir loopback adresine ayarlayarak başlatır. Cevap verecek bir program olmadığında hataları tarayıcıda gösterebilmesi bu sayede mümkündür.
collage dev yalnızca Host'u bu makineyi adlandıran request'lere cevap verir: localhost ya da onun altındaki bir ad, bir IP adresi, example.com ya da *.test gibi ayrılmış bir ad, başlatıldığı HOST veya COLLAGE_DEV_HOST içindeki bir ad. Diğer her şeyi 403 ile reddeder.
Başka bir sitedeki bir page, kendi adının 127.0.0.1'e çözümlenmesini sağlayabilir (DNS rebinding) ve böylece collage dev ile same-origin olur. Bu durumda page'lerinizi, stack'leriyle birlikte development hata sayfalarını ve programın çıktısını okuyabilir. Gönderdiği Host ise kendi adıdır ve bunu değiştiremez.
collage dev'e başka bir adla erişmek için onu HOST bu ada ayarlanmış olarak başlatın ya da adı COLLAGE_DEV_HOST içine yazın. Bu, virgülle ayrılmış bir listedir. Örneğin app,mybox.lan, bir docker-compose servisini ve bir LAN adını verir. collage dev onu shell'den ya da environment dosyasından okur ve kendi proxy'sine uygular. Programı da listeye kendi HOST'unu ekleyerek başlatır, çünkü program loopback'te dinler ama tarayıcının Host'unu görür. Program da development modunda aynı kuralı uygular.
collage dev, kendi proxy'si loopback dışında bir adrese bağlandığında ayrıca bir Warn log'lar, çünkü development sayfalarına o zaman başka makinelerden erişilebilir. Bkz. Deployment.
Programın yazdıkları terminale programın yazdığı gibi ulaşır, tek bir farkla: programın kendi adresi collage dev'in adresiyle değiştirilir. Böylece collage: listening satırı açmanız gereken adresi gösterir.
Renkli bir terminalde program FORCE_COLOR=1 ile başlatılır ve varsayılan logger bunu dikkate alır. Programın çıktısı collage dev'e bir pipe üzerinden ulaşsa da satırları saatini, renkli işaretlerini ve soluk attribute'larını korur. collage dev'in kendi satırları da aynı biçimdedir. NO_COLOR ikisini de kapatır.
16:10:23 • collage dev: serving http://localhost:6060
16:10:24 • collage: listening addr=localhost:6060
16:10:29 • collage dev: change detected, rebuilding
16:10:29 ✗ collage dev: build failed; waiting for a change
Scaffold edilen main.go, COLLAGE_DEV=1 ayarlı olduğunda development modunu açar ve kendisine verilen HOST ve PORT üzerinde dinler: collage.Main ikisini de newApp'e verdiği Env'e koyar. Development modu template'leri ve static dosyaları her request'te diskten okur. Bu yüzden onları düzenlediğinizde rebuild gerekmez ve rebuild yapılmaz; bunun yerine tarayıcınızdaki page kendini yeniler. Programınızın diskten kendisi okuduğu içerik de (örneğin Markdown), dizini Config.DevWatch içinde belirtildiğinde page'i yeniler. Development modunun başka neleri değiştirdiğini Template'ler sayfasında bulabilirsiniz.
Development build'leri hiçbir şey embed etmez
collage dev, go build -tags collage_dev ile build eder. Scaffold da //go:embed satırını //go:build !collage_dev ile başlayan embed.go dosyasında tutar. Yanındaki embed_dev.go (//go:build collage_dev) aynı değişkeni tanımlar. Development modu templates/ ve static/ dizinlerini zaten diskten okur, yani bir development build'inin embed edeceği bir şey yoktur. collage build, collage export ve düz bir go build tag vermez ve bu dizinleri embed eder.
İki dosya tek bir dosya sistemi tanımlar: files. embed.go'da bu //go:embed all:templates all:static plugins-config.json'dır; embed_dev.go'da ise proje dizininin kendisidir, os.DirFS("."). Böylece files verilen bir plugin (bir kart template'i, bir favicon kaynağı, Markdown yazılar) boş bir dosya sistemi yerine düzenlemekte olduğunuz kopyayı okur.
Sebebi Go build cache'idir. Dosya embed eden bir paket bu dosyaları derlenmiş hâlinde taşır. Projenizde herhangi bir yerdeki değişiklik main'i yeniden derler. Bu yüzden dosyaları embed eden her build, templates/ ve static/'in bir kopyasını daha cache'e yazar: her kaydetmede bir tane, beş gün boyunca saklanır. 30 MB'lık bir static/, cache'i her kaydetmede yaklaşık 30 MB büyütür; birkaç yüz kaydetme gigabaytlar eder.
Bir projenin main package'ı development build'inde dosya embed ediyorsa (yani //go:embed satırları main.go gibi !collage_dev constraint'i olmayan bir dosyadaysa) collage dev başlarken dosyanın adını vererek bunu söyler:
16:10:23 ! collage dev: main.go embeds files into every development build, and each build stores another copy of them in the Go build cache; move the //go:embed lines into a file constrained with //go:build !collage_dev (see collage help dev) patterns=all:static all:templates
Düzeltmek için //go:embed değişkenlerini main.go'dan (ve import'larındaki "embed"'i) çıkarıp kendilerine ait iki dosyaya taşıyın. Yeni bir projeye gelen dosyalar şunlardır:
// embed.go
//go:build !collage_dev
package main
import "embed"
//go:embed all:templates all:static plugins-config.json
var files embed.FS
// embed_dev.go
//go:build collage_dev
package main
import (
"io/fs"
"os"
)
var files fs.FS = os.DirFS(".")
Cache'te zaten birikmiş olanı go clean -cache geri kazandırır. Editörünüzdeki gopls tag'siz build ettiği için embed_dev.go'yu açtığınızda dosyanın build constraint'ler yüzünden dışarıda kaldığını söyler; bu beklenen bir durumdur.
Rebuild'i ne tetikler
| İzlenir | İzlenmez |
|---|---|
projenin herhangi bir yerindeki .go dosyaları | _test.go dosyaları |
proje kökündeki go.mod ve go.sum | template'ler, static dosyalar ve DevWatch dizinleri (rebuild olmadan yeniden yüklenir) |
proje kökündeki plugins-config.json | gizli dizinler (.git, .cache, …) |
| aşağıda anlatılan ortam dosyası | bin, dist, node_modules, testdata, vendor |
Atlanan dizinler, döngünün kendi kendini beslemesini engeller. Çalışan programın yazdığı hiçbir şey (cache'i ya da bir export) rebuild tetikleyemez. Program plugins-config.json'ı başlarken bir kez okur; bu yüzden orada düzenlenen bir ayar, koddaki bir değişiklikle aynı rebuild üzerinden programı yeniden başlatır.
Rebuild şöyle ilerler:
- Polling yapar. Her 300 ms'de bir dosyaların değişiklik zamanlarını ve boyutlarını karşılaştırır. Dosya sistemi bildirimleri için bir kütüphane kullanmaz ve her platformda aynı şekilde davranır.
- Art arda gelen yazmalar tek bir rebuild'dir. Bir değişiklikten sonra, dosyalar bir polling aralığı boyunca değişmeyene kadar bekler. Böylece birkaç dosyayı yeniden yazan bir formatter yalnızca bir build'e yol açar.
- Önce yeni build yapılır.
go build, binary'yi proje dışındaki geçici bir dizine yazar. Eski process ancak yeni binary derlendikten sonra durdurulur ve yenisi başlatılır. Eski process, Ctrl-C'de olduğu gibi elindeki request'leri bitirir. 10 saniye içinde çıkmazsa öldürülür. - Derlenmeyen bir değişiklikte de eski process durdurulur. Çalışmaya devam eden bir build artık kodla uyuşmaz ve terminal görünmüyorsa bunu söyleyen bir şey de olmaz. Bunun yerine derleyicinin hatası, aşağıda anlatıldığı gibi tarayıcıda görünür.
- Kendiliğinden çıkan bir program döngü içinde yeniden başlatılmaz. Örneğin açılışta panic olabilir ya da bir page'in template'i eksik olabilir. Program bir sonraki değişiklikte yeniden başlatılır.
Tarayıcıdaki hatalar
Çalışmayan bir program, reddedilen bir bağlantı değil, bir page'dir:
- Program çıktığında (register sırasında bulunamayan bir template, açılışta bir panic) ya da bir build başarısız olduğunda her page, programın ya da derleyicinin yazdıklarını gösteren bir 503'tür. Açık olan bir page yenilenerek bu page'e geçer. Bir değişiklik programı geri getirdiğinde de yeniden yenilenir.
- Program başlarken yapılan bir request onu bekler. Program henüz dinlemediği için başarısız olmaz.
- Kendisine söylenen yerde hiç dinlemeyen bir program, yani
HOSTvePORT'u yok sayan birmain.go, 10 saniye sonra, kendisine verilen adresle birlikte page'de belirtilir.
Program çalışırken başarısız olan bir render'da ise programın kendi development error page'i görünür. Bu page hatanın sebebiyle başlar. Bkz. Hatalar.
Ortam dosyaları
collage dev, bulunduğunuz dizindeki .env.development dosyasının değişkenlerini programın ortamına ekler. .env.development yoksa .env dosyasını kullanır. Her zaman tek bir dosya okunur, asla ikisi birden okunmaz: .env.development, .env'in üzerine merge edilmez, onun yerine geçer.
# .env.development
PORT=6060
HOST=localhost
export COLLAGE_CSRF_KEY="0f1e2d3c4b5a69788796a5b4c3d2e1f00f1e2d3c4b5a69788796a5b4c3d2e1f0"
- Dosya
KEY=valuesatırlarından, boş satırlardan ve#ile başlayan satırlardan oluşur. Satırın başındaexportolabilir. Bir değer, eşleşen tek ya da çift tırnak içine de alınabilir. Tırnaklar kaldırılır ve içlerindeki hiçbir şey yorumlanmaz. - Tırnaksız bir değer, boşluktan sonra gelen ilk
#işaretinde biter. YaniPORT=6060 # devsatırının değeri6060'tır. - Key'ler harf, rakam ve alt çizgiden oluşur ve rakamla başlayamaz.
- Hatalı bir satır programın başlamasını engeller.
collage devhatayı dosya adı ve satır numarasıyla (.env.development:3) bildirir. Satır düzeltilene kadar hiçbir şeyi başlatmaz ya da yeniden başlatmaz. Zaten çalışan bir program, başlatıldığı değerlerle çalışmaya devam eder.collage devizlemeyi sürdürür; düzeltilmiş dosyayı kaydettiğinizde kaldığı yerden devam eder. Hatalı satırı atlamak, yazdığınız bir ayarın programa hiç ulaşmaması demek olurdu. - Shell'de zaten ayarlı olan bir değişken dosyadakine göre önceliklidir. Bu yüzden
PORT=4000 collage devyine çalışır. - Dosyada ne yazarsa yazsın
COLLAGE_DEV=1her zaman ayarlanır. Programın dinleyeceğiHOSTvePORTda her zaman ayarlanır. DosyadakiHOSTvePORT,collage dev'in kendisinin dinlediği yerdir vecollage devbaşlarken bir kez okunur.COLLAGE_DEV_HOSTda dosyadan ya da shell'den okunur ve program onucollage dev'in kendiHOST'u eklenmiş olarak alır. BASE_URL, shell de dosya da onu ayarlamadığındacollage dev'in kendi adresidir:http://localhost:6060. Mutlak URL yazan bir plugin (sitemap, canonical link) origin olmadan başlamayı reddeder ve development'ta doğru origin budur. Deploy edildiğinde onu kendiniz ayarlayın.- Dosyanın olmaması hata değildir. Bir dosya okunduğunda adı stderr'e yazdırılır.
- Dosya her yeniden başlatmada tekrar okunur. Dosya izlendiği için onu düzenlediğinizde program yeni değerlerle yeniden başlar.
main fonksiyonu collage.Main'i çağıran bir program da bu dosyaları, scaffold edilen program gibi, aynı kurallarla okur. go run ., collage export ve derlenmiş binary, newApp çalışmadan önce çalışma dizinindeki .env'i yükler; COLLAGE_DEV=1 altında önce .env.development'a bakılır. Böylece os.Getenv("BASE_URL") onu source .env olmadan görür. Development dışında okunan dosyanın adı stderr'e yazdırılır. Değişkenlerini kendisi ayarlayan bir sunucuda değişkenler önceliklidir ve dosyanın olmaması hata değildir. Hatalı bir satır ise programı dosya ve satırıyla birlikte durdurur. collage.Main'i çağırmayan kendi yazdığınız bir main hiçbir dosya okumaz.
collage build
collage build [-o path] [-os name] [-arch name] [-i]
Bulunduğunuz dizindeki projeyi deploy edeceğiniz binary'ye derler. Çalıştırdığı komut şudur:
CGO_ENABLED=0 GOOS=<os> GOARCH=<arch> go build -trimpath -ldflags="-s -w" -o bin/<name> .
| Flag | Varsayılan | Anlamı |
|---|---|---|
-o path | bin/<name> | Binary'nin yazılacağı yer |
-os name | bu makineninki | Hedef işletim sistemi (GOOS) |
-arch name | bu makineninki | Hedef mimari (GOARCH) |
-i | kapalı | Binary'nin yanına hangi ek dosyaların yazılacağını sorar |
<name>, go.mod'daki module path'in son parçasıdır. Dizinde go.mod yoksa ya da go.mod bir module tanımlamıyorsa komut hata verir. -os windows verildiğinde, path zaten .exe ile bitmiyorsa sonuna .exe eklenir. Positional argümanlar kullanım hatasıdır.
Bu ayarların nedenleri:
- CGO kapalıdır, çünkü ne collage ne de standart kütüphane C'ye ihtiyaç duyar. Static bir binary, içinde başka hiçbir şey olmayan bir image'a konabilir.
-trimpathkullanılır, böylece binary onu derleyen makinedeki path'leri içermez.-s -wdebug tablolarını çıkarır. Boyutun büyük kısmı bu tablolardır.- Varsayılan hedef üzerinde çalıştığınız makinedir. Böylece binary derlendiği yerde çalışır. Sunucu çoğu zaman başka bir platformdur: Mac'te derlenen bir binary Linux container'ında çalışmaz. O yüzden sunucu için hedefi belirtin:
collage build -os linux -arch amd64. - Binary
dist/yerinebin/dizinine yazılır.dist/,collage export'un yazdığı yerdir veexport -cleanonu boşaltır.
İş bittiğinde binary'nin path'ini, platformunu, boyutunu ve build süresini yazdırır.
-i ile ek dosyalar
-i verildiğinde build'den önce iki soru sorar ve cevapları standart input'tan okur. y ya da yes evet anlamına gelir, diğer her şey hayır sayılır:
- Dockerfile yazılsın mı? İki aşamalı bir image'dır. İlk aşama bir
golangbuild aşamasıdır ve CLI'ı derleyen Go'nun major ve minor sürümüne sabitlenir. İkinci aşamagcr.io/distroless/static-debian12tabanlıdır ve yalnızca binary'yi içerir. Bu aşamadaHOST=0.0.0.0vePORT=8080ayarlanır, 8080 portu expose edilir veCOLLAGE_CSRF_KEYyorum satırı olarak bulunur. - systemd unit yazılsın mı?
/usr/local/bin/<name>binary'sini/srv/<name>dizininden çalıştıran bir<name>.servicedosyasıdır. İçindeHOST=127.0.0.1,PORT=8080,Restart=on-failureveTimeoutStopSec=30vardır. Kurmadan önce kendi ihtiyacınıza göre düzenlemeniz gerekir.
İki dosya da binary'nin yanına yazılır: bin/Dockerfile ve bin/<name>.service. Bunun nedeni, bu dosyaların üretilmiş olmasıdır; proje kökü ise insanların yazdığı dosyalar içindir. Bu yerleşimin tek bedeli farklı bir komuttur ve rapor o komutu yazdırır:
docker build -f bin/Dockerfile .
Var olan bir dosyanın üzerine asla yazılmaz. Dosya zaten varsa ilgili soru sorulmaz. Bunlar projelerin düzenlediği dosyalardır. Bu dosyaları varsayılan hâliyle değiştiren bir build komutu, birinin emeğini sessizce silmiş olurdu.
-i olmadan yalnızca binary yazılır. Ayrıntılar için Deployment sayfasına bakın.
collage export
collage export [-out dir] [-clean]
Bulunduğunuz dizindeki projeyi bir static host için static dosyalara render eder. HTML olabilen her page için HTML üretir, mount edilmiş bütün asset'leri de çıktıya ekler. Çalıştırdığı komut şudur:
go run . -collage-build -out <dir> # plus -clean when you passed it
| Flag | Varsayılan | Anlamı |
|---|---|---|
-out dir | dist | Projenin render edildiği dizin |
-clean | kapalı | Build'den önce dizinin mevcut içeriğini siler; yalnızca bir export'un oluşturduğu dizinde |
Programın çıktısı, yani build raporu, yeniden biçimlendirilmeden olduğu gibi aktarılır. Positional argümanlar kullanım hatasıdır.
-clean (BuildOptions.Clean) yalnızca bir export'un oluşturduğu dizini boşaltır: export, oluşturduğu ya da boş bulduğu dizine bir .collage-export işareti bırakır ve -clean bu işareti taşımayan bir dizinde hiçbir şey silmez. Projenin kendi dizinini (çalışma dizini, module kökü ya da repository kökü) ve onun üstündeki her dizini reddeder; bu yüzden -out .. -clean da -out static -clean da hiçbir şey silinmeden ya da yazılmadan önce ErrDangerousOutDir ile durur. Bu işaret olmadan export edilmiş bir dist/, işarete bir kez ihtiyaç duyar:
touch dist/.collage-export
Path'leri yalnızca büyük-küçük harfte ayrılan iki çıktı (/About ve /about) macOS'te ve Windows'ta tek bir dosyadır. Bu yüzden export bunları her platformda, aynı path'e düşen iki çıktı gibi bir çakışma (ErrOutputPathCollision) sayar ve hiçbir şey build etmez.
Strateji tanımlamayan bir page, render ettiği hiçbir şeyin data handler'ı yoksa export edilir. Handler'ı olan bir page ise Static() ya da Incremental(ttl) belirtiyorsa export edilir. Path'inde {param} olan bir page, WithStaticParams'ın listelediği her değer için bir kez export edilir; WithStaticParams yoksa atlanır. Neyin export edildiği, neyin hangi nedenle atlandığı ve çıktı dizini için yapılan güvenlik kontrolleri Static export sayfasında anlatılır. Form'ları ya da her request'te üretilen page'leri olan bir site için ihtiyacınız olan komut collage build'dir.
collage serve
collage serve [-dir dir] [-host name] [-port n]
Bir static export'u, bir static host'un sunacağı şekilde sunar. Böylece burada gördüğünüz, deploy ettikten sonra göreceğinizle aynıdır. Yalnızca dosya sunar, projenizi çalıştırmaz.
| Flag | Varsayılan | Anlamı |
|---|---|---|
-dir dir | dist | Sunulacak dizin |
-host name | localhost | Dinlenecek interface |
-port n | 4000 | Dinlenecek port |
Port 6060 değil 4000'dir, böylece collage dev ile yan yana çalışabilir. İkisini karşılaştırmak istediğiniz an da tam olarak budur.
Sıradan bir dosya sunucusu gibi değil, bir static host gibi davranır:
- Uzantısı olmayan bir path'e
<path>/index.htmlile cevap verilir. Export'un yazdığı yapı da budur. - Dizinler asla listelenmez.
- Hiçbir dosyaya karşılık gelmeyen bir path'e, export'un kendi
404.htmldosyası ve 404 status koduyla cevap verilir. Bu dosya yoksa sade bir 404 döner. - Yalnızca
GETveHEADrequest'lerine cevap verilir. Diğer her şey 405 alır. - Bir dotfile (
.env,.git/config) hiçbir zaman sunulmaz. Uzantısı bir tip belirtmeyen bir dosyanın tipi, mount'ta olduğu gibi içeriğinden belirlenir, ama hiçbir zaman HTML ya da XML olmaz. Her dosyanosniffile gider. - Her response
Cache-Control: no-storeheader'ıyla gönderilir. Böylece yeniden export edip sayfayı yenilediğinizde eski çıktıyı değil yenisini görürsünüz.
Dizin yoksa ya da içinde hiç dosya yoksa komut hata verir ve önce collage export çalıştırmanızı söyler. Path varsa ama dizin değilse de hata verir ve tam olarak bunu söyler.
collage routes
collage routes
Projenin collage üzerinden cevap verdiği her URL'yi, method ve path başına bir satır olarak, path'e göre sıralı listeler:
METHOD PATH KIND NAME NOTES
GET / page home static
GET /admin/users page users dynamic, guard adminGuard
POST /admin/users action rename on page users, guard adminGuard
POST /api/fire action fire own URL, own guard
POST /api/ping action ping own URL, no guard
GET /static/* mount 12 files
Not listed: handlers mounted with app.Handle, and plugins' own endpoints.
Bir page, nasıl cache'lendiğini ve hangi guard'lara sorulduğunu söyler. Bir action, bir page üzerinde mi (o zaman page'in guard'larına sorulur), yoksa kendi URL'sinde mi cevap verdiğini ve kendi guard'ı olup olmadığını söyler. Bir page'in fragment URL'leri de karşılaştıkları guard'larla listelenir. Sitenin birden fazla locale'i varsa bir LOCALE sütunu çıkar. Komut, collage inspect'in yazdırdığını okur; yani proje build edilir ve newApp çalışır. Collage üzerinden register edilmeyenler listede yoktur: app.Handle ile mount edilen handler'lar ve /healthz gibi plugin'lerin kendi endpoint'leri. Flag almaz.
collage inspect
collage inspect
Bulunduğunuz dizindeki projenin nelerden oluştuğunu JSON olarak yazdırır. Çıktıda pattern'leri, parametreleri, layouts'u (en dıştaki başta) ve guards'ıyla her page, template'i ve slot'larıyla her fragment (inline bir fragment "inline": true ile ve template path'i olmadan gelir), document'lar, action'lar, template fonksiyonları, plugin'ler, locale'ler ve mount'ların sunduğu dosyalar bulunur. Hiçbir flag almaz; positional argümanlar kullanım hatasıdır. Projeyi collage dev gibi derler ve programı COLLAGE_DEV=1 ile çalıştırır:
go build -tags collage_dev -o <geçici dosya> .
COLLAGE_DEV=1 <geçici dosya> collage-inspect
Programa hiçbir şey gömülmez; program templates/ ve static/ dizinlerini diskten okur. Derlenen program da ayrı bir dosyaya yazılır. Bunun nedeni şu: go run, derlediği programı Go build cache'ine koyar. Tag olmadan derlenen main paketi, scaffold'un gömdüğü bütün dosyaları içerir. Bu yüzden main'deki her değişiklikten sonraki her çalıştırma, bu dosyaların bir kopyasını daha cache'e eklerdi ve kopyalar günlerce orada kalırdı. collage routes ve collage check de projeyi aynı şekilde çalıştırır. Geçici dosya, komut bittiğinde ve kesildiğinde de (Ctrl-C, SIGTERM ya da SIGHUP) silinir.
Bu komutlar ayrıca COLLAGE_CLI_COMMAND değişkenini sordukları kelimeye ayarlar. Bu değişken ayarlıyken App.ListenAndServe sunucuyu açmayı reddeder ve nedenini döner. Böylece argümanlarını DispatchCommands'a hiç vermeyen bir main.go, komutu sonsuza kadar bir sunucuyu bekletmek yerine hemen hata verir.
collage-inspect, DispatchCommands'ın bir plugin'e iletmeden kendisinin cevapladığı bir komuttur: uygulamanın tarifini girintili JSON olarak yazdırır. Sözleşme bu JSON'dur; arkasındaki Go tipleri (App.Inspect, collage.Inspection, collage.InspectCommand) public API'nin parçası değildir.
Adı prefix'lidir, böylece hiçbir plugin'in komut adını elinden almaz. Scaffold edilen main.go, flag'lerinden sonraki kelimeyi DispatchCommands'a verir (bkz. Plugin komutları). Bu yüzden scaffold edilmiş bir projenin başka hiçbir şeye ihtiyacı yoktur. Argümanlarını bu şekilde dispatch etmeyen bir programın ise cevap verecek bir şeyi yoktur.
Bir editörün completion'ı da bunu okur. VS Code için Collage Snippets & Highlighter extension'ı (Editör desteği), {{pageURL "…"}} içindeki page adlarını, {{slot "…"}} içindeki slot'ları ve {{asset "…"}} içindeki dosyaları buradan önerir.
Her fragment, template'inin . olarak gördüğü Go tipini de taşır. Root da bu tiplerin ulaştığı tiplerin bir tablosu olan types'ı taşır. Böylece bir editör {{.'yı tamamlayabilir ve bir alan adını register sırasında olduğu gibi kontrol edebilir (bkz. Template'ler nasıl kontrol edilir):
"fragments": [
{"name": "post-body", "template": "pages/post.html", "handler": true, "dataType": "*blog.Post"},
{"name": "layout", "template": "layouts/master.html", "dataType": "nil"},
{"name": "legacy", "template": "pages/legacy.html", "handler": true, "dataType": null, "typeCheck": false}
],
"types": {
"blog.Post": {
"kind": "struct",
"fields": [
{"name": "Base", "type": "blog.Base", "embedded": true},
{"name": "ID", "type": "int"},
{"name": "Title", "type": "string"},
{"name": "Author", "type": "*blog.User"},
{"name": "Comments", "type": "blog.Comments"},
{"name": "Related", "type": "blog.Tags"}
],
"methods": [{"name": "URL", "args": 0, "returns": "string"}]
},
"blog.Base": {"kind": "struct", "fields": [{"name": "ID", "type": "int"}]},
"blog.Comments": {"kind": "slice", "elem": "blog.Comment"},
"blog.Tags": {"kind": "map", "key": "string", "elem": "[]blog.Post"},
"blog.User": {"kind": "struct", "fields": [{"name": "Name", "type": "string"}]}
}
dataTypeher zaman yazılır: Go tipi; verisi olmayan ya dacollage.Effectkullanan bir fragment için"nil"; tip bir interface olduğu ve bu yüzden page render edilene kadar bilinmediği durumda (anydönecek şekilde tanımlanmış bir handler)null.typeCheck: falseyalnızcaWithoutTypeCheck()ile oluşturulmuş bir fragment'te görünür.types, herhangi bir fragment'in veri tipinden alanlar, eleman ve key tipleri ve method sonuçları üzerinden ulaşılabilen her isimli tipi tutar. Her tip Go adıyla key'lenir ve export edilmiş alanlarını (promote edilenler dahil) ve kendisinin ve pointer'ının bir şey dönen export edilmiş method'larını içerir.- Export edilmiş bir embedded alan da bir alandır: template ona
{{.Base}}diye ulaşır. Bu alan"embedded": truetaşır, promote ettiği alanlar da her zamanki gibi yanında listelenir. - İsimli bir pointer, slice, array, map ya da chan, tuttuğu tipi
elemile verir. Map ayrıcakeyde taşır. - Bir tip bir kez listelenir, diğer her yerde adıyla anılır. Böylece özyinelemeli bir tip sonsuza gitmez. İsimsiz bir struct, Go yazımıyla listelenir. Diğer isimsiz bileşik tipler bir tip string'inin içinde yazılır (
[]blog.Comment). time.Timevetemplate.HTMLgibi standart kütüphane tipleri ayrıntılandırılmaz, yalnızca adıyla anılır.- Hiçbir fragment'in bilinen bir veri tipi yoksa
typesyazılmaz. - İki farklı tipin paylaştığı bir key (
modelsadlı iki pakettekimodels.User), alan ve method içermeden{"kind": "struct", "ambiguous": true}olarak yazılır ve editör onu bilinmeyen bir tip sayar.
- Export edilmiş bir embedded alan da bir alandır: template ona
Çıktının version'ı 1'dir.
collage check
collage check [-json]
Hiçbir şeyi render etmeden her template'in link'lerini kontrol eder. Adla kurulan bir link ({{pageURL "post" "slug" .Slug}}, {{pageURLIn "en" "about"}}, {{actionURL "logout"}}, {{fragmentURL "home" "clock"}}, {{localeURL "en"}}) template render edildiğinde ve yalnızca ona ulaşan page'de hata verir. check hepsini tek seferde bulur:
$ collage check
error [unknown-route] inline template of fragment "hello":4:16: {{pageURL "featurs"}}: collage: no page or document by that name: "featurs"; did you mean "features"?
| Kural | Anlamı |
|---|---|
unknown-route | Bu adda bir page, document, action ya da fragment path'i yoktur; register edilmiş en yakın ad önerilir |
route-params | Parametreler route'un pattern'ini doldurmaz: biri eksiktir, biri için placeholder yoktur ya da ad-değer çiftleri hâlinde değildir |
unreachable-locale | Hiçbir URL'nin taşıyamayacağı bir locale: ne Locale.Default'tur ne de Locale.Supported içindedir |
no-path-in-locale | Route'un, pageURLIn ya da fragmentURLIn'in belirttiği locale'de bir path'i yoktur |
Kontrolü framework'ün kendi URL builder'larıyla yapar. Bu yüzden bildirdiği şey, tam olarak bir render'ın hata vereceği şeydir. Yalnızca string literal olarak yazılmış adlar kontrol edilir: bir alandan gelen ad ({{pageURL .Name}}) ancak template render edildiğinde bilinir. Adı literal olmayan bir parametre de parametrelerin kontrol edilmemesine yol açar. Kendine ait bir locale'i olmayan bir link, route'u herhangi bir locale'de kurulabiliyorsa geçer, çünkü bir render varsayılan locale'e geri döner.
Bir şey bulduğunda 1 ile çıkar. Bu yüzden CI'da collage build'den önce yer alabilir. -json, bulguları bir editör için {level, rule, message} dizisi olarak yazdırır. Programı collage inspect gibi çalıştırır:
go build -tags collage_dev -o <geçici dosya> .
COLLAGE_DEV=1 <geçici dosya> collage-check
collage.DispatchCommands bu komuta uygulamayı başlatıp App.Check'i çağırarak cevap verir. Yani açılışta bir veritabanı açan bir program onu burada da açar. Bir test de aynı fonksiyonu çağırabilir:
if findings := app.Check(); len(findings) > 0 {
t.Errorf("broken links: %v", findings)
}
collage plugin
Projeye plugin ekler, plugin çıkarır ya da bir plugin repository'sini kontrol eder:
collage plugin add <plugin>... [-dir dir]
collage plugin del <plugin>... [-dir dir]
collage plugin check [-release] [-run] [dir]
collage plugin add elagoht/consent # github.com/elagoht/collage-consent
collage plugin add elagoht/sitemap@v0.3.1 # go get'in kabul ettiği bir sürüm
collage plugin add gitlab.com/kisi/plugin # bir module path, yazıldığı gibi kullanılır
collage plugin del elagoht/consent
collage plugin add elagoht/session elagoht/flash # birden fazla, sırayla
collage plugin add @prod # bir paket
collage plugin del @live elagoht/session
collage plugin check -release -run # bir plugin'in kendi repository'sinde
owner/name, github.com/<owner>/collage-<name> demektir. İlk parçasında nokta olan bir path ise module path'tir ve yazıldığı gibi kullanılır. add ve del, bulunduğunuz dizindeki projede ya da -dir'in gösterdiği projede çalışır. Bu dizinde go.mod ve bir package main bulunmalıdır.
add modülü go get ile indirir. @version verilmezse @upgrade ister: go.mod'da henüz olmayan bir modül için en son release'i, zaten olan bir modül için ise onu hiçbir zaman geriye almaz. Sonra modülün bir plugin olup olmadığını kontrol eder. Sözleşme plugin yazarlarının sayfasındadır:
- modülün kökünde,
name'iowner/nameolan bircollage.json. Kısa ad verdiysenizname, yazdığınız adla aynı olmalıdır; - plugin'in package'ı modülün kökünde olmalı,
package mainolmamalı; - hiçbir şey ayarlanmadan çağrılabilen bir
New: parametresiz, variadic ya da sıfır değeri yazılabilen tek parametreli. Bu, package'ın kendi export edilmiş bir struct'ı içinpkg.Options{}, pointer, interface, slice, map ya da func içinnildemektir; - bir release tag'i; pseudo-version olmaz.
Önce manifest'in requires dediği plugin'leri ekler. Sonra plugins.go'ya import'u ve çağrıyı yazar: manifest'inin order'ı daha büyük olan ilk girdinin önüne. plugins-config.json'a da boş bir bölüm ekler. En son go mod tidy çalıştırır:
$ collage plugin add elagoht/consent
added elagoht/consent v0.2.0
plugins.go consent.New(consent.Options{})
plugins-config.json "elagoht/consent": {}
elagoht/consent
The banner needs its categories and wording: set `"categories"` (at least one) and `"text"` (the default locale's wording, labelling every category; other locales under `"locales"`) in this plugin's section of `plugins-config.json`. Without categories the application does not start.
Docs: https://github.com/Elagoht/collage-consent
Ardından plugin'in sizden hâlâ beklediklerini manifest'inden yazdırır: setup notunu, eklediği template fonksiyonlarını (her birini açıklamasının ilk cümlesiyle) ve dokümantasyonunun adresini. Birden fazla plugin eklendiğinde (bir paket, new --with) bunlar en sonda, "What each plugin needs from you" başlığı altında bir arada gelir. Boş bölüm varsayılanlar demektir. Plugin'in zorunlu tuttuğu bir ayar eksikse bunu uygulama başlarken plugin'in kendisi bildirir.
- Import, package'ın adını taşır. Bu ad
plugins.go'nun bir import'unda ya da package'da herhangi bir yerde tanımlı bir adla çakışırsa<owner><Name>olur, gerekirse sonuna sayı eklenir. plugins.go'da zaten olan bir plugin ikinci kez eklenmez. Yalnızca sürümü değişir ve komut bunu söyler.- Var olan bölüm korunur. İki dosya da yerinde düzenlenir, bu yüzden argümanlarınız, yorumlarınız, sıralamanız ve biçimlendirmeniz olduğu gibi kalır.
- Yarım iş kalmaz. Ctrl-C dahil her hata,
go.mod,go.sum,plugins.goveplugins-config.jsondosyalarını eski hâline döndürür. Önceden olmayan bir dosya yeniden silinir.
plugins.go'su olmayan bir proje, bu dosyayı ilk add'inde alır. Komut da collage.New'a bir kez verilmesi gereken Plugins: plugins(), satırını yazdırır. Scaffold edilmiş bir projede ikisi de hazır gelir.
del, plugin'i plugins.go'nun girdileri arasında, manifest'lerindeki ada ya da module path'e göre, büyük küçük harfe bakmadan bulur. Girdilerini, import'unu ve bölümünü kaldırır, bölümde ayar varsa onu yazdırır ve go mod tidy çalıştırır. Şu durumlarda reddeder:
- başka bir plugin'in manifest'i onu
requiresediyorsa; - başka bir girdinin
collage.json'u okunamıyorsa (modül indirilemiyor ya da dosya bozuk). O plugin'in bunu isteyip istemediğini bilemez. Mesaj modülü ve nedeni belirtir; - ona bir module path verilmişse ve plugin'in kendi
collage.json'u okunamıyorsa, çünkü bölümünün adı bu durumda bilinmez.
Başka bir girdinin collage.json'undan yalnızca name, requires ve order okunur. Bu yüzden daha yeni bir manifest şemasından gelen bir anahtar hiçbir şeyi engellemez. Elle bağlanmış olup bir plugin modülünün kök package'ı olmayan girdi (kendi modülünüzün bir package'ı ya da bir bağımlılığın alt package'ı) ve collage.json'u hiç olmayan modül hiçbir şey istemez, hiçbir şeyi engellemez. Module cache'te olmayan bir modül (yeni bir clone'dan sonra olduğu gibi) manifest'i okunmak için indirilir. del de add gibi, bir adım başarısız olursa her dosyayı geri koyar.
Birden fazla plugin
add ve del birden fazla plugin alır ve onları verilen sırayla işler. Her biri ayrı bir adımdır: başarısız olan raporlanır ve geri alınır, öncesindekiler ve sonrasındakiler yerinde kalır. Komut bu durumda 1 ile çıkar. Okunamayan bir ad, iki farklı sürümle verilen bir plugin gibi, hiçbir şey değişmeden komutu durdurur. İki kez verilen bir plugin bir kez işlenir.
Birden fazla plugin verildiğinde sonda bir özet gelir; add, setup notlarını her plugin'in ardından değil, en sonda bir arada yazdırır:
$ collage plugin add elagoht/feed elagoht/nope elagoht/toc
added elagoht/feed v0.3.0
...
collage: plugin add: elagoht/nope: ...
added: elagoht/feed, elagoht/toc
failed: elagoht/nope
To finish setting up:
elagoht/feed
Feeds are Go values: give them to `feed.New(...)` in `plugins.go`, ...
Sırayı del sizin yerinize düşünür: listedeki başka bir plugin'in ihtiyaç duyduğu plugin, o plugin'den sonra silinir. Bu yüzden del elagoht/live elagoht/websocket çalışır.
Paketler
Paket, tek bir ad altında toplanmış plugin'lerdir ve @ ile yazılır: collage plugin add @prod, collage new site --with @blog. Plugin'leri aşağıdaki sırayla eklenir ve her biri plugins.go'da manifest'inin istediği yere gider. del @ad, paketin projede olan plugin'lerini siler, olmayanları atlar. collage help plugin da paketleri listeler.
| Paket | Ne için | Plugin'ler |
|---|---|---|
@prod | canlıdaki bir sitenin istedikleri | health, secure, compress, minimizer, accesslog, ratelimit |
@site | herkese açık bir sitenin arama ve paylaşım temelleri | robots, sitemap, meta, jsonld, favicon |
@blog | @site, bir feed, içindekiler ve paylaşım kartları | @site'ın plugin'leri, feed, toc, ogimage |
@forms | formlar ve cookie'de tutulan durum | session, flash, validate, honeypot |
@live | sunucunun güncel tuttuğu fragment'lar | live, websocket |
@ops | metrikler ve hata raporları | prometheus, errortrack |
Her plugin elagoht/<ad>'dır. Bazıları uygulama başlamadan önce bir ayar ister: sitemap ve meta sitenin origin'ini (scaffold edilmiş projede BASE_URL), favicon bir kaynak görseli, ogimage plugins.go'da verilen bir dosya sistemini, errortrack development dışında bir DSN'i. Ne yapılacağını setup notları söyler; yapılana kadar uygulama, eksik ayarın adını vererek başlamayı reddeder.
check, bir plugin repository'sini (dir, varsayılan .) add'in uyguladığı sözleşmeye göre kontrol eder. Kontrolün kendisi yalnızca repository'yi okur:
-releaseayrıcaHEAD'de bir release tag'i ister, bunun için git gerekir;-run, repository'nincollage-plugin-check/dizininde geçici bir program derleyip çalıştırır. Module cache'te olmayanı indirir. Dizinin adı her seferinde aynıdır, böylece Go build cache'i programın tek bir kopyasını tutar. Dizin zaten varsa (başka bir kontrol çalışıyordur ya da yarıda kesilmiştir)-runreddeder ve dizine dokunmaz. Bu programNew'uadd'in yazacağı biçimde, bircollage.Pluginolarak çağırır veName()'in manifest'tekinameolduğunu kontrol eder. Build hatasında,New'daki bir panic'te ya da farklı bir adda başarısız olur. Plugin'i configure etmez, başlatmaz; yani boş bir bölümde eksik kalan bir ayar onun işi değildir.go.mod,go.sumvego.work.sumeski hâline döner, program silinir.
Bunlar collage binary'sinin komutlarıdır. Bir plugin'in kendi alt komutları ise başka bir şeydir: bkz. Plugin komutları.
collage ai
collage ai init [--dir path]
collage new mysite --ai # the same, while scaffolding
Bir coding agent'ın (opencode, Codex, Cursor, Claude Code) collage projesinde çalışmak için ihtiyaç duyduğu kuralları projenin AGENTS.md dosyasına yazar. Kurallar her dosya türünün nereye gittiğini (ve collage add'in onu oraya koyduğunu), bir layout değişikliğinin altındaki her page'e ulaştığını, guard'ların bir action'a nasıl ulaştığını, CSS'in nasıl hoist edildiğini ve kendiniz yazmak yerine hangi plugin'i eklemeniz gerektiğini söyler. Kasıtlı olarak kısadırlar: collage'ı hiç görmemiş bir agent, çoğu zaman küçük bir model, önce onları okur ve kendi alışkanlıklarının önüne koyar.
collage yalnızca iki marker arasındaki kendi bölümünü yazar:
<!-- collage:begin v1.0.0 — written by `collage ai init`; … -->
…
<!-- collage:end -->
## Project rules
- collage'ı yükselttikten sonra komutu yeniden çalıştırın; o bölüm yenilenir. Marker'ların dışındaki her şey, yani projenin kendi kuralları, byte byte korunur.
- Marker'ları olmayan bir
AGENTS.md, bölümü metninin üstüne alır. - Bir begin satırı ve ardından bir end satırı biçiminde olmayan marker'lar reddedilir ve hiçbir şey yazılmaz. Hangi metnin collage'a ait olduğu bir tahmin olurdu ve yanlış bir tahmin kurallarınızı silerdi.
- Proje bir
CLAUDE.md'ye sahip değilse@AGENTS.mdiçeren birCLAUDE.mdde yazılır; böylece Claude Code aynı kuralları okur. Var olan birCLAUDE.mdasla değiştirilmez;AGENTS.md'yi import etmiyorsa komut bunu söyler.
Her dosyayla ne yaptığını yazdırır: created, updated ya da bölüm zaten yazacağı hâldeyse current:
AGENTS.md: created
CLAUDE.md: created
collage completion
collage completion bash|zsh|fish
TAB'a basıldığında komutları, flag'leri ve onların değerlerini tamamlayan bir script yazdırır: add'in türleri, plugin add'in paketleri ve onların adını verdiği plugin'ler, --template'in template'leri, --with'in listesi (öğe öğe) ve --dir, -o ile -out için path'ler. Script'i shell'in başlangıç dosyasından yükleyin:
eval "$(collage completion bash)" # ~/.bashrc (works with macOS's bash 3.2)
source <(collage completion zsh) # ~/.zshrc, after compinit
collage completion fish | source # ~/.config/fish/config.fish
Script neyin tamamlanacağını gizli bir collage __complete komutu üzerinden PATH'teki collage'a sorar. Bu yüzden bir yükseltmeden sonra da, yeniden yüklenecek bir şey olmadan doğru kalır. Her komutun flag'leri bir kez tanımlanır ve hem komut hem completion tarafından okunur; böylece yeni bir flag var olduğu gün tamamlanır. Bir projenin plugin'lerinin eklediği komutlar projenin kendi binary'si üzerinden çalışır ve tamamlanmaz.
collage man
collage man # print collage(1)
collage man --install # write it where man finds it
Her komutun kendi help metninden üretilen man sayfası collage(1)'i yazdırır. --install onu, collage'ı barındıran PATH dizininin yanındaki ../share/man/man1/collage.1 konumuna yazar: go install için $(go env GOPATH)/share/man, ~/.local/bin içindeki bir link için ~/.local/share/man. man, PATH'teki her dizin için orada arar; bu yüzden man collage başka hiçbir kurulum gerektirmeden çalışır. Binary PATH'te değilse ya da MANPATH, bu dizinleri dahil eden boş girdi olmadan ayarlanmışsa komut bunu söyler.
collage version
collage version
collage version <version> yazdırır. Sürüm, binary'nin build bilgisinden okunur. Bu yüzden go install ...@v1.0.0 ile kurulan binary 1.0.0 bildirir. Bir git checkout'unda derlenen binary ise bir pseudo-version bildirir. Örneğin v1.0.0 tag'inden sonraki bir commit için bu 1.0.1-0.<timestamp>-<commit> olur. Yalnızca hiç sürüm bilgisi olmayan bir binary devel bildirir. Bu, bir repository dışında ya da -buildvcs=false ile derlenmiş bir binary'dir.
collage help
collage help # every command
collage help export # one command's usage
Argümansız çalıştırıldığında bütün komutları listeler ve 0 ile çıkar. Bir komut adı verildiğinde o komutun kullanım bilgisini yazdırır. Bilinmeyen bir ad verildiğinde collage: unknown command: "nope" yazdırır; yakın bir komut varsa ardından onu önerir. Sonra 2 ile çıkar.
Örnek: yeni bir projeden ilk deploy'a
Bu bölüm, yukarıdaki komutları bir sitenin onlarla karşılaştığı sırayla izler. Proje, bir laptop'ta yazılan ve başka platformdaki bir sunucuya deploy edilen myblog adlı bir sitedir. Çıktıdaki saatler, boyutlar, hash'ler ve cache dizinleri sizin makinenizde farklı olur.
1. Scaffold edin.
collage new myblog
cd myblog
go mod tidy
new, minimal projeyi yazar ve sonraki adımları yazdırır:
Scaffolded "myblog" in myblog
Next steps:
cd myblog
go mod tidy
collage dev
Scaffold edilen go.mod yalnızca module adını ve Go sürümünü (1.26.11) içerir; collage'ı go mod tidy ekler.
2. Çalıştırın.
collage dev
01:13:17 • collage dev: serving http://localhost:6060
01:13:18 • collage: dev mode is rendering templates from disk, not the embedded copy root=templates
01:13:18 • collage: dev mode, using an in-memory cache instead of the configured disk cache
01:13:18 • collage: listening addr=localhost:6060
http://localhost:6060 adresinde Hello from myblog görünür. Çalışır hâlde bırakın: sonraki adım Go dosyaları ekler ve collage dev, dosyalar oluştuğunda projeyi yeniden build eder.
3. Bir page ekleyin ve link'leri kontrol edin. İkinci bir terminalde:
collage add page about
wrote fragments/pages/about.go
wrote pages/about.go
edited routes.go
locale en, from the default; main.go sets no Locale.Default literal, --locale changes it
page "about" at /about
collage dev yeniden build eder ve /about cevap verir. Ardından:
collage check
01:14:05 • collage: dev mode, using an in-memory cache instead of the configured disk cache
collage: check: nothing found
İlk satır programın kendisine aittir, çünkü check programı development modunda başlatır. İkincisi kontrolün sonucudur ve çıkış kodu 0'dır; CI'da bu, collage build'den önceki adımdır.
4. Sunucu için build edin. Laptop sunucu değildir, bu yüzden sunucunun platformunu belirtin ve iki ek dosyayı -i ile isteyin:
collage build -i -os linux -arch amd64
Building myblog for linux/amd64.
Write a Dockerfile? [y/N]: y
Write a systemd unit? [y/N]: y
✓ bin/myblog
linux/amd64 · 10.3 MB
wrote bin/Dockerfile docker build -f bin/Dockerfile .
wrote bin/myblog.service
10.3 MB · linux/amd64 · 6.7s
Scaffold'un .gitignore'u bin/myblog'u adıyla yok sayar, yanındaki iki dosyayı ise yok saymaz: onlar sizin düzenleyip commit edeceğiniz dosyalardır. Komutu yeniden çalıştırdığınızda iki soru da sorulmaz, çünkü dosyalar zaten vardır.
5. Sunucuya koyun. İki dosya, projeyi çalıştırmanın iki yoludur ve yalnızca biri bin/myblog'u kullanır:
- Servis unit'i, derlediğiniz binary'yi çalıştırır.
bin/myblog'u sunucuda/usr/local/bin/myblogkonumuna kopyalayın. Unit'inUserveWorkingDirectorydeğerlerini düzenleyin (dosya bunları bilemez) ve unit'i ilk yorum satırında belirtilen yere kurun. Önüne konacak bir reverse proxy için127.0.0.1:8080üzerinde dinler. - Image dosyası kendi binary'sini derler: ilk aşaması projeyi kaynaktan aynı flag'lerle derler, ikinci aşaması da sonucu taşır. Raporun söylediği gibi proje kökünden build edin.
0.0.0.0:8080üzerinde dinler.
8080 bu dosyaların kendi ayarıdır, PORT=8080 olarak yazılır. HOST ya da PORT verilmeden çalıştırılan binary, scaffold'un varsayılanı olan localhost:6060 üzerinde dinler; bkz. Deployment. İki dosyada da yorum satırı olarak bir COLLAGE_CSRF_KEY bulunur: onu en az 32 rastgele byte'a ayarlayın. Aksi hâlde her process için bir key üretilir ve bir restart'tan önce gönderilen her form, restart'tan sonra reddedilir.
Plugin'leri -i'den önce ekleyin. Image dosyası plugins-config.json'ı yalnızca dosya yazıldığı sırada projede varsa kopyalar ve -i dosyayı hiçbir zaman yeniden yazmaz. Sonradan eklenen bir plugin için o COPY satırını elle eklemeniz gerekir.
Ya da export edin. Dosya sunan bir host için collage export -clean, bunun yerine dist/'i render eder ve raporu yeni page'i dışarıda bırakır:
✓ 3 files written
dist/index.html
dist/static/app.css
dist/static/app.f106e88ebb47f51d.css
▲ 1 skipped
about page uses the dynamic render strategy, which cannot be built statically
3 written · 1 skipped · 0 failed · 1.5ms
collage add, about'a bir collage.Load handler'ı verdi ama strateji vermedi, bu yüzden page dynamic'tir. pages/about.go içindeki builder'ına .Static() ekleyin; bir sonraki export dist/about/index.html'i de yazar. Ardından collage serve, dist/'i localhost:4000'de bir static host'un sunacağı gibi gösterir.
main.go ile sözleşme
dev, export ve inspect, main.go'nuzun yaptığı üç şeye dayanır. Scaffold edilen main.go'nun çağırdığı collage.Main üçünü de yapar. Üçüncüsü, flag'lerden sonraki kelimeleri collage.DispatchCommands'a vermektir. Plugin'lerinizin komutlarını çalıştıran da budur:
| Komut | Çalıştırdığı | main.go'nuzun yapması gereken |
|---|---|---|
collage dev | önce go build -tags collage_dev, sonra binary; COLLAGE_DEV=1, dinlenecek HOST ile PORT ve COLLAGE_DEV_HOST ayarlı olarak | COLLAGE_DEV1 olduğunda development modunu açmak ve HOST ile PORT üzerinde dinlemek |
collage export | go run . -collage-build -out <dir> [-clean] | -collage-build, -out ve -clean flag'lerini parse etmek; -collage-build verildiğinde sunmak yerine <dir> dizinine render etmek |
collage inspect | önce go build -tags collage_dev, sonra binary; collage-inspect ve COLLAGE_DEV=1 ile (routes ve check de böyle) | COLLAGE_DEV1 olduğunda development modunu açmak ve flag'lerden sonraki kelimeleri collage.DispatchCommands'a vermek |
collage build'in main.go'dan hiçbir beklentisi yoktur. Derleme, go build'in kendisine hiçbir şey söylenmeden yaptığı bir iştir.
Scaffold edilen main.go bunların hepsini collage.Main'e bırakır:
func main() {
collage.Main(newApp)
}
func newApp(env collage.Env) (*collage.App, error) {
pluginConfig, err := env.PluginConfig(files)
if err != nil {
return nil, err
}
app, err := collage.New(&collage.Config{
DevMode: env.Dev,
BaseURL: os.Getenv("BASE_URL"),
Server: collage.ServerConfig{Host: env.Host, Port: env.Port},
Template: collage.TemplateConfig{
FS: files,
Root: "templates",
Extension: ".html",
},
Cache: collage.CacheConfig{
Enabled: true,
Type: "disk",
Dir: env.CacheDir,
DefaultTTL: 5 * time.Minute,
},
PluginConfig: pluginConfig,
Plugins: plugins(),
Security: collage.SecurityConfig{
CSRFKey: []byte(os.Getenv("COLLAGE_CSRF_KEY")),
},
})
if err != nil {
return nil, err
}
if err := register(app); err != nil {
return nil, err
}
return app, app.Mount("/static/", env.Static(files, "static"))
}
collage.Mainortam dosyasını yükler; -collage-build, -out, -clean ve -port flag'lerini parse eder ve newApp'i bir collage.Env ile çağırır:
| Alan | Değer |
|---|---|
Dev | collage dev'in ayarladığı COLLAGE_DEV=1 |
Host | HOST ya da localhost |
Port | -port, PORT ya da 6060 |
CacheDir | .cache; bir test kendine ait bir dizin verir |
env.PluginConfig(files), plugins-config.json çalışma dizininde varsa onu okur; böylece bir deployment bir ayarı rebuild olmadan değiştirebilir. Yoksa binary'nin embed ettiği kopyayı okur; böylece dosyası olmadan deploy edilen bir binary ayarlarını korur. env.Static(files, "static"), static dizinini development'ta diskten, diğer durumlarda embed edilmiş hâlinden sunar. Ardından collage.Main bir plugin'in komutunu dispatch eder, -collage-build verildiğinde -out'a render eder ya da hizmet verir. Bir build'den ya da bir komuttan sonra uygulamayı shutdown eder.
Bir test newApp(collage.Env{CacheDir: t.TempDir()}) çağırır. collage.Main olmadan yazılmış bir main sözleşmeyi şöyle yerine getirir (burada yalnızca önemli kısmı bırakılmıştır):
func main() {
buildFlag := flag.Bool("collage-build", false, "render the app to static files instead of serving it")
outFlag := flag.String("out", "dist", "output directory for -collage-build")
cleanFlag := flag.Bool("clean", false, "remove -out's existing contents before building")
port := 6060 // -port, then PORT, then 6060
if p, err := strconv.Atoi(os.Getenv("PORT")); err == nil {
port = p
}
portFlag := flag.Int("port", port, "port to listen on (env PORT)")
flag.Parse()
host := os.Getenv("HOST")
if host == "" {
host = "localhost"
}
app, err := newApp(collage.Env{
Dev: os.Getenv("COLLAGE_DEV") == "1",
Host: host,
Port: *portFlag,
CacheDir: ".cache",
})
if err != nil {
log.Fatal(err)
}
// A word after the flags is a plugin's command: go run . <command>
if args := flag.Args(); len(args) > 0 {
code, err := collage.DispatchCommands(context.Background(), app, args)
if err != nil {
fmt.Fprintln(os.Stderr, err)
}
if err := shutdown(app); err != nil {
fmt.Fprintf(os.Stderr, "shutdown: %v\n", err)
code = max(code, 1)
}
os.Exit(code)
}
if *buildFlag {
buildErr := staticBuild(app, *outFlag, *cleanFlag)
if err := shutdown(app); err != nil {
log.Printf("shutdown: %v", err)
buildErr = errors.Join(buildErr, err)
}
if buildErr != nil {
log.Fatalf("static build: %v", buildErr)
}
return
}
if err := app.ListenAndServe(); err != nil {
log.Fatal(err)
}
}
// shutdown runs every plugin's Shutdown once a build or a command is done.
// Neither serves, so nothing else would. Only after a successful start: a start
// that failed has already shut down the plugins it started.
func shutdown(app *collage.App) error {
if app.Start() != nil {
return nil
}
ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
return app.Shutdown(ctx)
}
// staticBuild renders the application into outDir and prints the report.
func staticBuild(app *collage.App, outDir string, clean bool) error {
report, err := collage.Build(context.Background(), app, collage.BuildOptions{
OutDir: outDir,
Clean: clean,
})
collage.PrintBuildReport(os.Stdout, report, err)
return err
}
Bir build ve bir komut hizmet vermez, bu yüzden ListenAndServe onlar için uygulamayı hiçbir zaman shutdown etmez. collage.Main, ikisinden biri bittiğinde app.Shutdown'ı kendisi çağırır; kendi yazdığınız bir main bunu yukarıdaki gibi yapar. Böylece her plugin'in Shutdown'ı çalışır: bir plugin'in elinde tuttuğu şey flush edilir ve elagoht/jobs gibi bir queue plugin'ine verilen iş, drop edildiğinde en azından loglanır.
main'i collage.Main olmadan yazarsanız bunların hepsinin çalışmaya devam ettiğinden emin olun. Aksi hâlde collage dev, collage export, collage inspect ve plugin'lerinizin komutları projenizde işe yarar hiçbir şey yapmaz.
Plugin komutları
Plugin eklemek ve çıkarmak collage plugin işidir. Bu bölüm ise plugin'in kendi alt komutlarını anlatır. Bir plugin, Host.RegisterCommand ile bir komut ekleyebilir. collage CLI bu komutu çalıştırmaz. CLI uygulamanızı hiçbir zaman yüklemez. Bu yüzden ancak plugin'leriniz başladıktan sonra var olan bir komuta CLI erişemez ve collage <plugin-command> bilinmeyen bir komut olarak kalır.
Bu komutları kendi programınız collage.DispatchCommands ile dispatch eder. Scaffold edilen main.go'nun çağırdığı collage.Main bunu zaten yapar. Kendi yazdığınız bir main bunu şöyle yapar (yukarıdaki blok): flag'ler parse edilip uygulama kurulduktan sonra geriye kalan bir kelime komut olarak yorumlanır:
if args := flag.Args(); len(args) > 0 {
code, err := collage.DispatchCommands(context.Background(), app, args)
if err != nil {
fmt.Fprintln(os.Stderr, err)
}
if err := shutdown(app); err != nil { // see above
fmt.Fprintf(os.Stderr, "shutdown: %v\n", err)
code = max(code, 1)
}
os.Exit(code) // runs no defers, so the shutdown comes first
}
DispatchCommands uygulamayı başlatır. Bunu yaparken her plugin'in Init'ini çalıştırır; plugin'ler komutlarını Init içinde register eder. Ardından ilk argümanın adını taşıyan komutu çalıştırır. Böylece bir plugin'in komutu, programınızın bir alt komutu olarak ve varsa flag'lerden sonra çalışır:
go run . pages
./bin/myblog -port 4000 pages
Çıkış kodları CLI'ınkilerle aynı mantığı izler:
| Kod | Ne zaman |
|---|---|
0 | başarı |
1 | açılış hatası, çalışıp başarısız olan bir komut ya da Run'ı olmayan bir komut |
2 | nil bir app, argüman verilmemesi ya da hiçbir plugin'in register etmediği bir kelime (ErrUnknownCommand) |
Hiçbir komuta karşılık gelmeyen bir kelime, yanlışlıkla başlatılmış bir sunucuya değil, kullanım hatasına yol açar. Hiçbir plugin'in register etmediği bir kelimeye yine de cevap verilir: collage inspect komutunun çalıştırdığı collage-inspect. Hiçbir komut eşleşmediğinde sunucuyu başlatmayı tercih eden bir program, errors.Is(err, collage.ErrUnknownCommand) ile kontrol edip çıkmak yerine devam edebilir. Kendi kullanım metninizi yazdırmak isterseniz app.Commands() plugin'lerin register ettiği komutları listeler.
RegisterCommand, hiçbir zaman çalıştıramayacağı bir adı reddeder: tek bir shell kelimesi olmayan bir ad (collage.ErrInvalidCommandName), DispatchCommands'ın kendisinin cevapladığı bir collage- adı ve bir plugin'in komutu için collage binary'sinin kendi adlarından biri (ikisi de collage.ErrDuplicateCommand). Uygulama başladıktan sonra collage.ErrAppStarted'tır: o sırada register edilen bir komut hiç çalışmazdı. Bkz. Plugin yazmak.
Dispatch işlemi uygulamayı başlatır ve bu da register aşamasını kapatır. Sonradan çağrılan ListenAndServe aynı başlatmayı yeniden kullanır. DispatchCommands uygulamayı shutdown etmez, çünkü bir program ardından onunla hizmet vermeye devam edebilir. Bir komut çalıştıktan sonra, yukarıdaki gibi app.Shutdown'ı kendiniz çağırın. Böylece her plugin'in Shutdown'ı çalışır. collage.Main de bunu yapar. Böyle bir komutun nasıl yazıldığı Plugin yazmak sayfasında anlatılır.