تنظیمات Finch در pubspec.yaml
بخش finch در فایل pubspec.yaml تنظیمات پروژه را در اختیار Finch CLI قرار میدهد. فرمانهایی مانند finch run، finch serve، finch build، finch migrate --create و finch make:migration از این بخش برای پیدا کردن فایل ورودی، منابع پروژه، مسیر خروجی build و محل ساخت migration استفاده میکنند.
این تنظیمات با FinchConfigs تفاوت دارند. بخش finch رفتار ابزار خط فرمان را مشخص میکند، اما FinchConfigs تنظیمات خود برنامه هنگام اجرا، مانند پورت، دیتابیس و مسیر فایلهای استاتیک، را نگه میدارد.
نمونه کامل
# Finch configuration
# See https://pub.dev/packages/finch for more details
# Here you can customize paths and settings for your Finch application
# They will be used by Finch CLI commands to run, build, serve, migrate, etc.
# Adjust these settings as needed for your project structure
finch:
# Main path of the application
app: ./lib/app.dart
# Path of serve file while developing
serve: ./lib/serve.dart
# Path of languages files
languages_path: ./lib/languages
# Type of languages files
languages_type: json
# Path of templates (widgets) files
widgets_path: ./lib/widgets
# Type of templates (widgets) files
widgets_type: j2.html
# Path of migrations files for different databases
mysql_migrate:
path: ./migrations
type: sql
# Path of migrations files for different databases
sqlite_migrate:
path: ./lib/dart_migration
type: dart
build_output: ./build_example
public_path: ./public
مسیرهای نسبی بر اساس دایرکتوری جاری که فرمان finch در آن اجرا میشود تفسیر میشوند. معمولاً باید فرمانها را از ریشه پروژه، یعنی محل فایل pubspec.yaml، اجرا کنید. هنگام ساخت ProjectCommands نیز CLI فایل pubspec.yaml را در همین دایرکتوری جاری پیدا و بخش finch را بارگذاری میکند.
فایلهای ورودی برنامه
app
مسیر فایل اصلی برنامه برای فرمان زیر است:
finch run
در نمونه بالا، CLI دستور dart run را برای ./lib/app.dart اجرا میکند. اگر گزینه --path یا -p ارسال شود، مقدار خط فرمان بهجای app استفاده خواهد شد:
finch run --path ./lib/another_app.dart
اگر app تنظیم نشده باشد، CLI در مسیرهای متداول مانند bin، lib و src به دنبال نامهایی مانند app.dart و server.dart میگردد و در نهایت مسیر را از کاربر میپرسد.
نکته: در پیادهسازی فعلی، فرمان
finch buildمستقیماً کلیدappرا نمیخواند. برای تعیین فایل ورودی build از--appPathیا-aاستفاده کنید. در غیر این صورت build از مقدار داخلیpathو سپس./lib/app.dartاستفاده میکند.
serve
مسیر فایل ورودی محیط توسعه برای فرمان زیر است:
finch serve
این فرمان علاوه بر اجرای فایل تعیینشده، Dart VM Service را نیز فعال میکند تا روند توسعه و reload پروژه در دسترس باشد. گزینه --path یا -p بر مقدار serve اولویت دارد:
finch serve --path ./lib/watcher.dart
فایل معرفیشده باید واقعاً در پروژه وجود داشته باشد و entry point مناسب اجرای برنامه را فراهم کند.
فایلهای زبان
languages_path
دایرکتوری فایلهای ترجمه را مشخص میکند. مقدار پیشفرض CLI در صورت نبود این کلید ./lib/languages است.
فرمان finch build این دایرکتوری را در خروجی build و در مسیر lib/languages کپی میکند. گزینه --langPath یا -l مقدار این کلید را برای همان اجرای build بازنویسی میکند:
finch build --langPath ./lib/languages
اگر مسیر خالی باشد یا دایرکتوری وجود نداشته باشد، مرحله کپی فایلهای زبان انجام نمیشود.
languages_type
پسوند فایلهای ترجمه را بدون نقطه ابتدایی تعیین میکند. برای فایلهایی مانند fa.json و en.json مقدار آن باید json باشد.
هنگامی که build داخلی برنامه باید ترجمهها را به Dart تبدیل کند، LanguageToDart فقط فایلهایی با این پسوند را میخواند و فایل language_dart.g.dart را داخل languages_path تولید میکند. مقدار پیشفرض json است.
قالبها
widgets_path
دایرکتوری قالبهای Jinja را مشخص میکند. مقدار پیشفرض CLI در صورت نبود این کلید ./lib/widgets است.
فرمان finch build محتوای این دایرکتوری را در lib/widgets خروجی build کپی میکند. گزینه --widgetPath یا -w برای همان فرمان بر مقدار فایل تنظیمات اولویت دارد:
finch build --widgetPath ./lib/widgets
اگر مسیر خالی باشد یا دایرکتوری وجود نداشته باشد، مرحله کپی قالبها انجام نمیشود.
widgets_type
پسوند قالبها را بدون نقطه ابتدایی تعیین میکند. برای فایلهایی مانند home.j2.html مقدار صحیح j2.html است.
هنگامی که build داخلی برنامه قالبها را به Dart تبدیل کند، WidgetToDart فایلهای منطبق با این پسوند را به map قالبها تبدیل کرده و فایل widget_dart.g.dart را در widgets_path میسازد. مقدار پیشفرض CLI برای این تبدیل html است.
migrationهای دیتابیس
mysql_migrate
تنظیمات ساخت migration برای MySQL است:
mysql_migrate:
path: ./migrations
type: sql
path: دایرکتوری ساخت فایل migration جدید.type: پسوند و نوع قالب فایل migration؛ معمولاًsql.
این مقدارها توسط finch migrate --create و finch make:migration خوانده میشوند:
finch migrate --create --name create_users
finch make:migration --name create_users
نام فایل تولیدشده شامل timestamp، نام migration و پسوند تعیینشده است. گزینه --path یا -p در finch make:migration میتواند مسیر را برای همان اجرا تغییر دهد.
sqlite_migrate
تنظیمات ساخت migration برای SQLite است:
sqlite_migrate:
path: ./lib/dart_migration
type: dart
با ارسال گزینه --sqlite یا -s، CLI بهجای تنظیمات MySQL این بخش را میخواند:
finch make:migration --sqlite --name create_books
finch migrate --create --sqlite --name create_books
در پروژه نمونه، نوع dart باعث ساخت migration دارت در ./lib/dart_migration میشود. این بخش محل ساخت فایل جدید را برای CLI تعیین میکند؛ مسیر اجرای migrationهای ثبتشده در زمان اجرای برنامه از تنظیمات و ثبت migration در FinchApp میآید.
خروجی build
build_output
دایرکتوری پیشفرض خروجی finch build را مشخص میکند:
build_output: ./build_example
خروجی build شامل فایل اجرایی در lib/app.exe و، در صورت وجود، کپی فایلهای public، زبان و قالب است. گزینه --output یا -o بر این مقدار اولویت دارد:
finch build --appPath ./lib/app.dart --output ./release
اگر دایرکتوری تنظیمشده در build_output از قبل وجود داشته باشد، CLI آن را برای build جدید پاک و دوباره ایجاد میکند. اما اگر یک مسیر سفارشی موجود با --output بدهید، build برای جلوگیری از بازنویسی آن متوقف میشود.
مقدار پیشفرض در نبود این کلید ./finch_build است.
فایلهای public
public_path
دایرکتوری فایلهای عمومی مانند CSS، JavaScript، تصویر و فونت را برای مرحله build تعیین میکند:
public_path: ./public
اگر این دایرکتوری وجود داشته باشد، finch build آن را در پوشه public خروجی کپی میکند. گزینه --publicPath یا -p در فرمان build بر این مقدار اولویت دارد:
finch build --publicPath ./public
مقدار پیشفرض در نبود این کلید ./public است. این تنظیم فقط منبع کپی در build را مشخص میکند؛ مسیر سرو فایلهای استاتیک هنگام اجرای برنامه همچنان باید در FinchConfigs.publicDir تنظیم شود.
اولویت تنظیمات
هر جا فرمان CLI گزینه متناظر داشته باشد، ترتیب انتخاب مقدار به این شکل است:
- گزینه ارسالشده در خط فرمان
- مقدار بخش
finchدرpubspec.yaml - مقدار پیشفرض داخلی Finch CLI
برای نمونه، در فرمان زیر مقدار --output جایگزین build_output و مقدار --appPath فایل ورودی build را تعیین میکند:
finch build \
--appPath ./lib/app.dart \
--output ./release \
--publicPath ./public \
--langPath ./lib/languages \
--widgetPath ./lib/widgets
بهتر است مسیرهای ثابت پروژه را در pubspec.yaml نگه دارید و گزینههای خط فرمان را برای اجرای موقت با مسیر متفاوت به کار ببرید.