diff --git a/docs/getting-started/folder-structure.ja.md b/docs/getting-started/folder-structure.ja.md new file mode 100644 index 00000000..e3dd10ed --- /dev/null +++ b/docs/getting-started/folder-structure.ja.md @@ -0,0 +1,81 @@ +# フォルダ構造 + +あなたの初めての Vapor アプリを作成し、ビルドし、実行したので、Vapor のフォルダ構造に慣れるための時間を取りましょう。この構造は、[SPM](spm.ja.md) のフォルダ構造に基づいていますので、以前に SPM を使ったことがあれば、見慣れているはずです。 + +``` +. +├── Public +├── Sources +│ ├── App +│ │ ├── Controllers +│ │ ├── Migrations +│ │ ├── Models +│ │ ├── configure.swift +│ │ ├── entrypoint.swift +│ │ └── routes.swift +│ +├── Tests +│ └── AppTests +└── Package.swift +``` + +以下のセクションでは、フォルダ構造の各部分について詳しく説明します。 + +## Public + +このフォルダには、`FileMiddleware` が有効になっている場合にアプリによって提供される公開ファイルが含まれます。これは通常、画像やスタイルシート、ブラウザスクリプトです。例えば、`localhost:8080/favicon.ico` へのリクエストは、`Public/favicon.ico` が存在するかどうかを確認し、それを返します。 + +Vapor が公開ファイルを提供できるようにする前に、`configure.swift` ファイルで `FileMiddleware` を有効にする必要があります。 + +```swift +// Serves files from `Public/` directory +let fileMiddleware = FileMiddleware( + publicDirectory: app.directory.publicDirectory +) +app.middleware.use(fileMiddleware) +``` + +## Sources + +このフォルダには、プロジェクトのすべての Swift ソースファイルが含まれています。 +トップレベルのフォルダ、`App` は、[SwiftPM](spm.ja.md) のマニフェストで宣言されたパッケージのモジュール反映をしています。 + +### App + +ここには、アプリケーションの全てのロジックが入ります。 + +#### Controllers + +Controllers は、アプリケーションのロジックをまとめるのに適しています。ほとんどのコントローラには、リクエストを受け取り、何らかの形でレスポンスを返す多くの関数があります。 + +#### Migrations + +Migrations フォルダは、Fluent を使用している場合、データベースの移行を格納する場所です。 + +#### Models + +Models フォルダは、`Content` 構造体や Fluent の `Model` を保存するのに適しています。 + +#### configure.swift + +このファイルには、`configure(_:)` 関数が含まれています。このメソッドは、新しく作成された `Application` を設定するために `entrypoint.swift` から呼び出されます。ここで、ルート、データベース、プロバイダなどのサービスの登録をする必要があります。 + +#### entrypoint.swift + +このファイルには、Vapor アプリケーションの設定と実行を行うアプリケーションの `@main` エントリーポイントが含まれています。 + +#### routes.swift + +このファイルには、`routes(_:)` 関数が含まれています。このメソッドは、`Application` へのルートを登録するために、`configure(_:)` の終わり近くで呼び出されます。 + +## Tests + +`Sources` フォルダ内の各非実行可能モジュールには、`Tests` の対応するフォルダがあります。これには、パッケージのテストのために `XCTest` モジュールに基づいてビルドされたコードが含まれています。テストは、コマンドラインで `swift test` を使用するか、Xcode で ⌘+U を押すと実行できます。 + +### AppTests + +このフォルダには、`App` モジュールのコードの単体テストが含まれています。 + +## Package.swift + +最後に、[SPM](spm.ja.md) のパッケージマニフェストがあります。 diff --git a/docs/getting-started/hello-world.ja.md b/docs/getting-started/hello-world.ja.md new file mode 100644 index 00000000..77d9a0e4 --- /dev/null +++ b/docs/getting-started/hello-world.ja.md @@ -0,0 +1,84 @@ +# Hello, world + +このガイドは、新しい Vapor プロジェクトを作成、ビルド、サーバーを実行する手順を説明します。 + +まだ、Swift や Vapor ツールボックスをインストールしていない場合は、インストールセクションを参照してください。 + +- [Install → macOS](../install/macos.ja.md) +- [Install → Linux](../install/linux.ja.md) + +## 新規プロジェクト + +最初のステップは、コンピュータに新しい Vapor プロジェクトを作成することです。ターミナルを開き、ツールボックスの新規プロジェクトコマンドを使用してください。これにより、現在のディレクトリにプロジェクトを含む新しいフォルダが作成されます。 + +```sh +vapor new hello -n +``` + +!!! tip + `-n` フラグは、すべての質問に自動的に「いいえ」と答えることで、ベアボーンのテンプレートを提供します。 + +!!! tip + Vapor ツールボックスを使用せずに GitHub [テンプレートリポジトリ](https://github.com/vapor/template-bare)をクローンして最新のテンプレートを取得することもできます。 + +!!! tip + Vapor and the template now uses `async`/`await` by default. + Vapor テンプレートは、デフォルトで `async`/`await` を使用します。 + macOS 12 にアップデートできない、または `EventLoopFuture` を継続して使用する必要がある場合は、 + `--branch macos10-15` フラグを使います。 + +コマンドが完了したら、新しく作成されたフォルダに移動します。 + + +```sh +cd hello +``` + +## ビルド & 実行 + +### Xcode + +まず、Xcode でプロジェクトを開きます： + +```sh +open Package.swift +``` + +自動的に Swift Package Manager の依存関係をダウンロードし始めます。プロジェクトを初めて開くとき、時間がかかることがあります。依存関係の解決が完了すると、Xcode は利用可能なスキームを表示します。 + +ウィンドウの上部に、再生ボタンと停止ボタンの右側にあるプロジェクト名をクリックして、プロジェクトのスキームを選択します。適切な実行ターゲットを選択してください。おそらく、"My Mac" が適しているでしょう。プレイボタンをクリックして、プロジェクトをビルドして実行します。 + +Xcode のウィンドウの下部に、コンソールが表示されるはずです。 + +```sh +[ INFO ] Server starting on http://127.0.0.1:8080 +``` + +### Linux + +Linux やその他 OS (または　Xcode を使用したくない場合の macOS も含む)では、 Vim や VScode のようなお好きなエディタでプロジェクトを編集できます。他の IDE の設定に関する最新の詳細は、[Swift Server ガイド](https://github.com/swift-server/guides/blob/main/docs/setup-and-ide-alternatives.md)を参照してください。 + +プロジェクトをビルドして実行するには、ターミナルで以下のコマンドを実行します: + +```sh +swift run +``` + +これにより、プロジェクトがビルドされて実行されます。初めてこれを実行すると、依存関係を取得および解決するのに時間がかかります。実行が開始されると、コンソールに以下の内容が表示されるはずです: + +```sh +[ INFO ] Server starting on http://127.0.0.1:8080 +``` + +## Localhost へのアクセス + +ウェブブラウザを開き、localhost:8080/hello または http://127.0.0.1:8080 にアクセスしてください。 + +次のページが表示されるはずです。 + + +```html +Hello, world! +``` + +おめでとうございます！ Vapor アプリの作成、ビルド、実行することに成功しました！ 🎉 diff --git a/docs/getting-started/spm.ja.md b/docs/getting-started/spm.ja.md new file mode 100644 index 00000000..f5b7baec --- /dev/null +++ b/docs/getting-started/spm.ja.md @@ -0,0 +1,95 @@ +# Swift Package Manager + +[Swift Package Manager](https://swift.org/package-manager/) (SPM) は、プロジェクトのソースコードと依存関係のビルドに使用されます。Vapor は SPM に大きく依存しているため、SPM の基本的な動作を理解することがおすすめです。 + +SPM は Cocoapods 、Ruby gems 、 NPM に似ています。SPM は、`swift build` や `swift test` などのコマンドでコマンドラインから使用することも、互換性のある IDE から使用することもできます。しかし、他のパッケージマネージャとは異なり、SPM パッケージのための中央のパッケージインデックスは存在しません。SPM は代わりに、Git リポジトリへの URL を利用し、[Git タグ](https://git-scm.com/book/en/v2/Git-Basics-Tagging)を使用して依存関係のバージョンを管理します。 + +## パッケージマニフェスト + +SPM がプロジェクトで最初に探す場所は、パッケージマニフェストです。これは常にプロジェクトのルールディレクトリに配置され、`Package.swift` という名前でなければなりません。 + +以下は、パッケージマニフェストの例です。 + +```swift +// swift-tools-version:5.8 +import PackageDescription + +let package = Package( + name: "MyApp", + platforms: [ + .macOS(.v12) + ], + dependencies: [ + .package(url: "https://github.com/vapor/vapor.git", from: "4.76.0"), + ], + targets: [ + .executableTarget( + name: "App", + dependencies: [ + .product(name: "Vapor", package: "vapor") + ] + ), + .testTarget(name: "AppTests", dependencies: [ + .target(name: "App"), + .product(name: "XCTVapor", package: "vapor"), + ]) + ] +) +``` + +以下のセクションでは、マニフェストの各部分を説明していきます。 + +### Tools Version + +パッケージマニフェストの最初の行は、必要な Swift ツールのバージョンを示しています。これは、パッケージがサポートする Swift のバージョン間で Package description API が変更される場合があるため、この行は Swift がマニフェストをどのように解析するかを知らせるために必要ようです。 + +### Package Name + +`Package` への最初の引数は、パッケージの名前です。パッケージが公開されている場合、Git リポジトリの URL の最後のセグメントを名前として使用する必要があります。 + +### Platforms + +`platforms` 配列は、このパッケージがサポートするプラットフォームを指定します。 +`.macOS(.v12)` を指定することで、このパッケージは macOS 12 以降が必要です。Xcode でこのプロジェクトをロードすると、利用可能な API を全て使用できるように、最小のデプロイメントバージョンが自動的に macOS 12 に設定されます。 + +### Dependencies + +依存関係は、パッケージが依存している他の SPM パッケージです。全ての Vapor アプリケーションは Vapor パッケージに依存していますが、必要に応じて他の依存関係を追加することができます。 + +上の例では、[vapor/vapor](https://github.com/vapor/vapor)のバージョン 4.76.0 以降がこのパッケージの依存関係であることがわかります。パッケージに依存関係を追加すると、次にどの[ターゲット](#targets)が新しく利用可能になったモジュールに依存しているかを示す必要があります。 + + +### Targets + +ターゲットは、パッケージが含むすべてのモジュール、実行ファイル、テストです。ほとんどの Vapor アプリは 2 つのターゲットを持っていますが、コードを整理するために必要なだけ多くのターゲットを追加することができます。各ターゲットは、それが依存するモジュールを宣言します。コード内でそれらをインポートするためには、ここでモジュールの名前を追加する必要があります。ターゲットは、プロジェクト内の他のターゲットや、[主な依存関係](#dependencies)配列に追加したパッケージで公開されている任意のモジュールに依存することができます。 + +## フォルダ構造 + +以下は、SPM パッケージの典型的なフォルダ構造です。 + +``` +. +├── Sources +│ └── App +│ └── (Source code) +├── Tests +│ └── AppTests +└── Package.swift +``` + +各 `.target` や `.executableTarget` は、`Sources` 内のフォルダに対応しています。 +各`.testTarget` は、`Tests` 内のフォルダに対応しています。 + +## Package.resolved + +プロジェクトを初めてビルドすると、SPM は各依存関係のバージョンを保存する `Package.resolved` ファイルを作成します。次にプロジェクトをビルドするとき、新しいバージョンが利用可能であっても、これらの同じバージョンが使用されます。 + +依存関係を更新するには、`swift package update` を実行します。 + +## Xcode + +もし、Xocde 11 以降を使用している場合、`Package.swift` ファイルが変更されるたびに、依存関係、ターゲット、プロダクトなどの変更が自動的に行われます。 + +最新の依存関係に更新するには、File → Swift Packages → Update To Latest Swift Package Versions を使用します。 + +また、`.swiftpm` ファイルを `.gitignore` に追加することもおすすめします。これは、Xcode がXcode project の設定を保存する場所です。 diff --git a/docs/getting-started/xcode.ja.md b/docs/getting-started/xcode.ja.md new file mode 100644 index 00000000..c8df08d9 --- /dev/null +++ b/docs/getting-started/xcode.ja.md @@ -0,0 +1,44 @@ +# Xcode + +このページでは、Xcode の仕様に関するいくつかのヒントとテクニックを紹介します。異なる開発環境を使用している場合、このセクションはスキップしてもよいです。 + +## カスタムワーキングディレクトリ + +デフォルトでは、Xcode はあなたのプロジェクトを _DerivedData_ フォルダから実行します。このフォルダは、プロジェクトのルートフォルダ ( _Package.swift_ ファイルがある場所) とは異なります。これは、 Vapor が _.env_ や _Public_ のようなファイルやフォルダを見つけることができないことを意味します。 + +アプリを実行するときに以下の警告が表示される場合、この問題が発生していることがわかります。 + +```fish +[ WARNING ] No custom working directory set for this scheme, using /path/to/DerivedData/project-abcdef/Build/ +``` + +これを修正するには、プロジェクトの Xcode スキームでカスタムワーキングディレクトリを設定します。 + +まず、プレイボタンとストップボタンの隣にあるスキームセレクタをクリックして、プロジェクトのスキームを編集します。 + +![Xcode Scheme Area](../images/xcode-scheme-area.png) + +ドロップダウンから _Edit Scheme..._ を選択します。 + +![Xcode Scheme Menu](../images/xcode-scheme-menu.png) + +スキームエディタで、_App_ アクションと _Options_ タブを選択します。_Use custom working directory_ をチェックし、プロジェクトのルートフォルダへのパスを入力します。 + +![Xcode Scheme Options](../images/xcode-scheme-options.png) + +プロジェクトのルートへのフルパスは、その場所で開いたターミナルウィンドウから `pwd` を実行することで取得できます。 + +```fish +# verify we are in vapor project folder +vapor --version +# get path to this folder +pwd +``` + +以下のような出力が表示されるはずです。 + +``` +framework: 4.x.x +toolbox: 18.x.x +/path/to/project +``` diff --git a/docs/install/linux.ja.md b/docs/install/linux.ja.md new file mode 100644 index 00000000..fba3e833 --- /dev/null +++ b/docs/install/linux.ja.md @@ -0,0 +1,63 @@ +# Linux にインストール + +Vapor を使用するには、Swift 5.6 以上が必要です。これは、[Swift.org](https://swift.org/download/)で利用可能なツールチェーンを使用してインストールできます。 + +## サポートされているディストリビューションとバージョン + +Vapor は、Swift 5.6 またはそれ以降のバージョンがサポートする Linux ディストリビューションのバージョンをサポートしています。 + +!!! 注意 + 下記のサポートされているバージョンは、古くなる可能性があります。公式にサポートされているオペレーションシステムは、[Swift Releases](https://swift.org/download/#releases) のページで確認できます。 + + +|ディストリビューション|バージョン|Swift のバージョン| +|-|-|-| +|Ubuntu|20.04|>= 5.6| +|Fedora|>= 30|>= 5.6| +|CentOS|8|>= 5.6| +|Amazon Linux|2|>= 5.6| + +公式にはサポートされていない Linux ディストリビューションでも、ソースコードをコンパイルすることで、Swift を実行できるかもしれませんが、Vapor は安定性を保証できません。[Swift repo](https://github.com/apple/swift#getting-started) から Swift のコンパイル方法について詳しく学ぶことができます。 + +## Swift のインストール + +Linux 上で Swift をインストールする方法については、Swift.org の[ダウンロードの使用](https://swift.org/download/#using-downloads)を参照してください。 + +### Fedora + +Fedora ユーザーは、以下のコマンドを使用して Swift を簡単にインストールできます: + +```sh +sudo dnf install swift-lang +``` + +Fedora 30 を使用している場合、Swift 5.6 またはそれ以降のバージョンを取得するには、EPEL8 を追加する必要があります。 + +## Docker + +Swift の公式Docker イメージも使用できます。これにはコンパイラが事前にインストールされています。[Swift の Docker Hub](https://hub.docker.com/_/swift) で詳しく学ぶことができます。 + +## ツールボックスのインストール + +Swift をインストールしたら、[Vapor Toolbox](https://github.com/vapor/toolbox) をインストールしましょう。この CLI ツールは、Vapor を使用するために必須ではありませんが、役立つユーティリティが含まれています。 + +Linux 上では、ソースからツールボックスをビルドする必要があります。GitHub のツールボックスのリリースで最新バージョンを見つけてください。 + +```sh +git clone https://github.com/vapor/toolbox.git +cd toolbox +git checkout +make install +``` + +インストールが成功したかどうかを確認するためにヘルプを表示します。 + +```sh +vapor --help +``` + +利用可能なコマンドのリストが表示されるはずです。 + +## 次へ + +Swift をインストールしたら、[はじめに → hello, world](../getting-started/hello-world.md) で初めてのアプリを作成してください。 diff --git a/docs/install/macos.ja.md b/docs/install/macos.ja.md new file mode 100644 index 00000000..f4c7f825 --- /dev/null +++ b/docs/install/macos.ja.md @@ -0,0 +1,49 @@ +# macOS へのインストール + +Vapor を macOS で使用するには、Swift 5.6 以上が必要です。Swift とそれに関連するすべての依存関係は、Xcode にバンドルされています。 + +## Xcode のインストール + +Mac App Store から[Xcode](https://itunes.apple.com/us/app/xcode/id497799835?mt=12) をインストールします。 + +![Xcode in Mac App Store](../images/xcode-mac-app-store.png) + +Xcode のダウンロードが完了したら、インストールを完了するために開く必要があります。これには時間がかかる場合があります。 + + +インストールが成功したことを確認するために、Terminal を開いて Swift のバージョンを表示してください。 + +```sh +swift --version +``` + +Swift のバージョン情報が表示されるはずです。 + +```sh +swift-driver version: 1.75.2 Apple Swift version 5.8 (swiftlang-5.8.0.124.2 clang-1403.0.22.11.100) +Target: arm64-apple-macosx13.0 +``` + +Vapor 4 は、Swift 5.6 以上が必要です。 + +## Toolbox のインストール + +Swift をインストールしたので、次に [Vapor Toolbox](https://github.com/vapor/toolbox) をインストールしましょう。このCLIツールはVapor を使用するためには必須ではありませんが、新しいプロジェクトクリエイーターのような便利なユーティリティが含まれています。 + +Toolbox は Homebrew 経由で配布されています。まだ Homebrew をインストールしていない場合は、brew.sh を参照してインストール手順を確認してください。 + +```sh +brew install vapor +``` + +インストールが成功したかどうかを確認するために、ヘルプを表示してください。 + +```sh +vapor --help +``` + +利用可能なコマンドのリストが表示されるはずです。 + +## 次へ + +Swift と Vapor Toolbox をインストールしたので、 [はじめに → Hello, world](../getting-started/hello-world.md) で初めてのアプリを作成してください。