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]
KomutNe yapar
newYeni bir collage projesi scaffold eder
addBulunduğunuz projeye bir page, fragment, action, document, layout, guard, middleware ya da command yazar
devBulunduğunuz dizindeki projeyi development modunda çalıştırır
buildBulunduğunuz dizindeki projeyi deploy edeceğiniz binary'ye derler
exportBulunduğunuz dizindeki projeyi static dosyalara render eder
serveBir static export'u, bir static host'un sunacağı şekilde sunar
routesBulunduğunuz dizindeki projenin cevap verdiği her URL'yi, her birinin karşılaştığı guard'larla listeler
inspectBulunduğunuz dizindeki projenin nelerden oluştuğunu JSON olarak yazdırır
checkBulunduğunuz dizindeki projenin template'lerini render etmeden kontrol eder
pluginProjeye plugin ekler, çıkarır ya da bir plugin repository'sini kontrol eder
aiProjenin coding agent'lar için kurallarını içeren AGENTS.md'yi yazar ya da günceller
completionbash, zsh ya da fish için bir shell completion script'i yazdırır
mancollage'ın man sayfasını yazdırır ya da man'in bulacağı yere kurar
versioncollage CLI'ın sürümünü yazdırır
helpBir 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.

Bir projenin collage komutları boyunca hayatı. collage new, projeyi bu dizinde scaffold eder. Proje üzerinde çalışırken: collage add bir page, fragment, action ya da document yazar; collage dev projeyi localhost:6060'ta çalıştırır ve Go kodu değiştiğinde yeniden build eder; collage check template'lerin link'lerini kontrol eder; collage plugin add ve del, plugins.go'yu ve go.mod'u düzenler; collage inspect projeyi JSON olarak yazdırır. Yayına almak için iki yol vardır. collage build, bin/ içine tek bir static binary derler; -i ile yanına bir image dosyası ve bir servis unit'i de yazar. Binary bir sunucuya gider ve orada HOST ile PORT'u okur. Ya da collage export, HTML ve static dosyaları dist/ içine render eder; collage serve dist/'i localhost:4000'de gösterir, bir static host da aynı dosyaları sunar.collage newbu dizindeki projecollage addcollage devcollage checkGo dosyası yazar:6060'ta çalışırlink kontrolücollage plugin add/delcollage inspectplugins.go ve go.modJSON olarak yazdırırcollage buildcollage exportbin/<name>tek bir static binarydist/HTML ve static dosyalar-i: image dosyasıve servis unit'icollage servelocalhost:4000bir sunucuHOST ve PORT'u okurbir static hostaynı dosyaları sunar
Bir projenin komutlar boyunca hayatı. 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ı

KodAnlamı
0Başarılı. help, collage -h ve collage <command> -h de bu kodla çıkar
1Komut doğru parse edildi ama işini yapamadı
2Kullanı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.

FlagVarsayılanAnlamı
--template nameminimalScaffold edilecek proje: minimal ya da demo
--with pluginsyokProje 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
-forcekapalıDizin boş olmasa da scaffold eder
--aikapalı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 verilen collage.Env'den config'i ve static mount'u kuran newApp ile onu collage.Main'e veren bir main. collage.Main, aşağıda anlatılan CLI sözleşmesini yerine getirir ve plugin komutlarını dispatch eder;
  • files'ı tanımlayan embed.go ve embed_dev.go: template'ler, static dosyalar ve plugins-config.json embed edilir, development build'inde ise proje dizininin kendisi kullanılır (bkz. aşağısı);
  • boş bir plugins.go ile plugins-config.json ve bir .env.example;
  • bütün route'ları register eden bir routes.go;
  • sitenin adını WithTitle ile 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.Value ile alan bir ana sayfa (içinde hiçbir şey veri çekmediği için Static() demeden static'tir);
  • static/, bir .gitignore ve 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
FlagVarsayılanAnlamı
--filekapalı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 nameson parçaPage'in, action'ın, document'ın ya da command'ın adı
--locale codeLocale.Default ya da enPath'in ait olduğu locale
--type typetext/plain; charset=utf-8Bir document'ın content type'ı
--layout nameyokBir page'in layout'u: add layout <name>'in yazdığı layout, sitenin layout'unun içinde
--guard nameyokadd guard <name>'in yazdığı guard ile .WithGuard(guards.<Name>): bir page'in içeriğinde, bir layout'ta ya da bir action'da
--page targetyokBir action'ın page'i, [area/]name: action'ı o page'e ekler
--dir path.Proje
  • Bir page, layouts.Master() ile (ya da fragments/layouts içinde argüman almayan ilk layout ile) sarılmış bir pages/<area>/<name>.go dosyasıdır. İçeriği fragments/pages/<area>/<name>.go içindedir: bir template, bir view struct'ı ve page'in başlığını belirten, tipli bir collage.Load handler'ı. 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>.go dosyası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>pages olması gibi <area>actions (blogactions) adıyla import edilir. Alanı olmayan bir action actions/<name>.go dosyasıdır. Zaten actions/<area>.go dosyalarında ya da actions/funcs/ içinde duran action'lara dokunulmaz; yenileri onların yanına, klasörlere yazılır. --path verildiğ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'in NewPage zincirini bitiren Build()'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. --path ile birlikte verilemez.
  • Bir document, documents/<name>.go dosyası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, --file ile 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:nested ile 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>.go dosyasıdır, guard fonksiyonunun kendisi: siz kontrolünü yazana kadar herkesi 403 ile reddeden bir GuardFunc. Bir request'i geçirmek için nil, 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ılacak add 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 admin guard'ı ona doğrudan verir.
  • Bir middleware, her request'i bir sonrakine geçiren bir func(http.Handler) http.Handler olan middleware/<name>.go dosyasıdır. app.Use ile, 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.RegisterCommand ile register edilen bir collage.Command olan commands/<name>.go dosyasıdır: go run . <name> ya da build edilmiş binary'nin ardından bu ad, sunucu yerine onu çalıştırır. --name ona Go adı olmayan bir ad verir, örneğin user-add. Projede başka bir collage.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.App alması ve error dö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, partials olur. Bir page'in içeriğinin yanında duracak bir fragment collage add fragment pages/blog/related ile 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.sumtemplate'ler, static dosyalar ve DevWatch dizinleri (rebuild olmadan yeniden yüklenir)
proje kökündeki plugins-config.jsongizli 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 HOST ve PORT'u yok sayan bir main.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=value satırlarından, boş satırlardan ve # ile başlayan satırlardan oluşur. Satırın başında export olabilir. 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. Yani PORT=6060 # dev satırının değeri 6060'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 dev hatayı 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 dev izlemeyi 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 dev yine çalışır.
  • Dosyada ne yazarsa yazsın COLLAGE_DEV=1 her zaman ayarlanır. Programın dinleyeceği HOST ve PORT da her zaman ayarlanır. Dosyadaki HOST ve PORT, collage dev'in kendisinin dinlediği yerdir ve collage dev başlarken bir kez okunur. COLLAGE_DEV_HOST da dosyadan ya da shell'den okunur ve program onu collage dev'in kendi HOST'u eklenmiş olarak alır.
  • BASE_URL, shell de dosya da onu ayarlamadığında collage 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> .
FlagVarsayılanAnlamı
-o pathbin/<name>Binary'nin yazılacağı yer
-os namebu makineninkiHedef işletim sistemi (GOOS)
-arch namebu makineninkiHedef mimari (GOARCH)
-ikapalı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.
  • -trimpath kullanılır, böylece binary onu derleyen makinedeki path'leri içermez.
  • -s -w debug 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/ yerine bin/ dizinine yazılır.dist/, collage export'un yazdığı yerdir ve export -clean onu 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 golang build aşamasıdır ve CLI'ı derleyen Go'nun major ve minor sürümüne sabitlenir. İkinci aşama gcr.io/distroless/static-debian12 tabanlıdır ve yalnızca binary'yi içerir. Bu aşamada HOST=0.0.0.0 ve PORT=8080 ayarlanır, 8080 portu expose edilir ve COLLAGE_CSRF_KEY yorum satırı olarak bulunur.
  • systemd unit yazılsın mı?/usr/local/bin/<name> binary'sini /srv/<name> dizininden çalıştıran bir <name>.service dosyasıdır. İçinde HOST=127.0.0.1, PORT=8080, Restart=on-failure ve TimeoutStopSec=30 vardı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
FlagVarsayılanAnlamı
-out dirdistProjenin render edildiği dizin
-cleankapalı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.

FlagVarsayılanAnlamı
-dir dirdistSunulacak dizin
-host namelocalhostDinlenecek interface
-port n4000Dinlenecek 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.html ile 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.html dosyası ve 404 status koduyla cevap verilir. Bu dosya yoksa sade bir 404 döner.
  • Yalnızca GET ve HEAD request'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 dosya nosniff ile gider.
  • Her response Cache-Control: no-store header'ı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"}]}
}
  • dataType her zaman yazılır: Go tipi; verisi olmayan ya da collage.Effect kullanan bir fragment için "nil"; tip bir interface olduğu ve bu yüzden page render edilene kadar bilinmediği durumda (any dönecek şekilde tanımlanmış bir handler) null.
  • typeCheck: false yalnızca WithoutTypeCheck() 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": true taşır, promote ettiği alanlar da her zamanki gibi yanında listelenir.
    • İsimli bir pointer, slice, array, map ya da chan, tuttuğu tipi elem ile verir. Map ayrıca key de 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.Time ve template.HTML gibi 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 types yazılmaz.
    • İki farklı tipin paylaştığı bir key (models adlı iki paketteki models.User), alan ve method içermeden {"kind": "struct", "ambiguous": true} olarak yazılır ve editör onu bilinmeyen bir tip sayar.

Çı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"?
KuralAnlamı
unknown-routeBu adda bir page, document, action ya da fragment path'i yoktur; register edilmiş en yakın ad önerilir
route-paramsParametreler route'un pattern'ini doldurmaz: biri eksiktir, biri için placeholder yoktur ya da ad-değer çiftleri hâlinde değildir
unreachable-localeHiçbir URL'nin taşıyamayacağı bir locale: ne Locale.Default'tur ne de Locale.Supported içindedir
no-path-in-localeRoute'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'i owner/name olan bir collage.json. Kısa ad verdiyseniz name, yazdığınız adla aynı olmalıdır;
  • plugin'in package'ı modülün kökünde olmalı, package main olmamalı;
  • 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çin pkg.Options{}, pointer, interface, slice, map ya da func için nil demektir;
  • 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.go ve plugins-config.json dosyaları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 requires ediyorsa;
  • 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.

PaketNe içinPlugin'ler
@prodcanlıdaki bir sitenin istediklerihealth, secure, compress, minimizer, accesslog, ratelimit
@siteherkese açık bir sitenin arama ve paylaşım temellerirobots, sitemap, meta, jsonld, favicon
@blog@site, bir feed, içindekiler ve paylaşım kartları@site'ın plugin'leri, feed, toc, ogimage
@formsformlar ve cookie'de tutulan durumsession, flash, validate, honeypot
@livesunucunun güncel tuttuğu fragment'larlive, websocket
@opsmetrikler 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:

  • -release ayrıca HEAD'de bir release tag'i ister, bunun için git gerekir;
  • -run, repository'nin collage-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) -run reddeder ve dizine dokunmaz. Bu program New'u add'in yazacağı biçimde, bir collage.Plugin olarak çağırır ve Name()'in manifest'teki name olduğ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.sum ve go.work.sum eski 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.md içeren bir CLAUDE.md de yazılır; böylece Claude Code aynı kuralları okur. Var olan bir CLAUDE.md asla 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/myblog konumuna kopyalayın. Unit'in User ve WorkingDirectory değerlerini düzenleyin (dosya bunları bilemez) ve unit'i ilk yorum satırında belirtilen yere kurun. Önüne konacak bir reverse proxy için 127.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ı olarakCOLLAGE_DEV1 olduğunda development modunu açmak ve HOST ile PORT üzerinde dinlemek
collage exportgo 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:

AlanDeğer
Devcollage dev'in ayarladığı COLLAGE_DEV=1
HostHOST 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:

KodNe zaman
0başarı
1açılış hatası, çalışıp başarısız olan bir komut ya da Run'ı olmayan bir komut
2nil 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.