diff --git a/docs/README.md b/docs/README.md index b77c420a..e9c499fb 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,11 +1,26 @@ # Functions Framework for Dart +These docs will help you get started with the [Functions Framework for Dart], +an open source **FaaS** (Function as a Service) framework that lets you write +and deploy lightweight, event-driven functions. + ## Contents -[1 Introduction](01-introduction.md) -[2 Quickstart: Dart](quickstarts/01-quickstart-dart.md) -[3 Quickstart: Docker](quickstarts/02-quickstart-docker.md) -[4 Quickstart: Cloud Run](quickstarts/03-quickstart-cloudrun.md) +[Introduction](01-introduction.md) + +### Setting up + +[Install dartfn](quickstarts/00-install-dartfn.md) + +### Quickstarts + +[Quickstart: Dart](quickstarts/01-quickstart-dart.md) +[Quickstart: Docker](quickstarts/02-quickstart-docker.md) +[Quickstart: Cloud Run](quickstarts/03-quickstart-cloudrun.md) --- [[next]](01-introduction.md) + + +[functions framework for dart]: +https://github.com/GoogleCloudPlatform/functions-framework-dart diff --git a/docs/quickstarts/00-install-dartfn.md b/docs/quickstarts/00-install-dartfn.md new file mode 100644 index 00000000..511360ad --- /dev/null +++ b/docs/quickstarts/00-install-dartfn.md @@ -0,0 +1,100 @@ +# Installing and using dartfn + +`dartfn` is a command-line (CLI) tool for working with Dart Functions Framework +projects. In this early version of the tool, you can use it to generate sample +projects from templates. Currently there are three templates: + +- helloworld - a basic HTTP handler function +- json - a simple function handler that accepts and sends JSON +- cloudevent - a simple cloudevent function handler + +## Prerequisites + +- [Dart SDK] v2.10+ + +## Install dartfn + +To install `dartfn` on your machine, run the following command: + +```shell +dart pub global activate dartfn +``` + +Output + +```text +dart pub global activate functions_framework_tool +Resolving dependencies... (1.2s) +... +Precompiling executables... (1.1s) +Precompiled functions_framework_tool:dartfn. +Installed executable dartfn. +Activated functions_framework_tool 0.3.0. +``` + +## Using dartfn + +### List available generators + +```shell +dartfn generate --list +``` + +Output + +```text +Available generators: +cloudevent - A sample Functions Framework project for handling a cloudevent. +helloworld - A sample "Hello, World!" Functions Framework project. +json - A sample Functions Framework project for handling JSON. +``` + +### Generate a project + +Generate a `helloworld` project, for example: + +```shell +mkdir helloworld +cd helloworld +dartfn generate helloworld +``` + +Output + +```text +project: demo +Creating helloworld application `ex`: + demo/.gitignore + demo/Dockerfile + demo/README.md + demo/analysis_options.yaml + demo/bin/server.dart + demo/lib/functions.dart + demo/pubspec.yaml + demo/test/function_test.dart +8 files written. + +--> to provision required packages, run 'pub get' +``` + +### Get the new project package dependencies + +```shell +dart pub get +``` + +Output + +```text +Resolving dependencies... (2.1s) +... +Changed 74 dependencies! +``` + +--- +[[toc]](../README.md) +[[back]](../01-introduction.md) +[[next]](01-quickstart-dart.md) + + +[Dart SDK]: https://dart.dev/get-dart diff --git a/docs/quickstarts/01-quickstart-dart.md b/docs/quickstarts/01-quickstart-dart.md index bb232593..1c768045 100644 --- a/docs/quickstarts/01-quickstart-dart.md +++ b/docs/quickstarts/01-quickstart-dart.md @@ -10,8 +10,12 @@ normal developer workflow. ## Get a copy of the `hello` example -Clone this repo or download a [zip] archive and extract the contents. Change -directory to `examples/hello`. +You can either + +* Run `dartfn` to create a new project using the `helloworld` generator (see + [Installing and using dartfn]) +* Clone this repo or download a [zip] archive and extract the contents + * Change directory to `examples/hello`. ## Build the example @@ -159,12 +163,13 @@ Listening on :8080 --- [[toc]](../README.md) -[[back]](../01-introduction.md) +[[back]](00-install-dartfn.md) [[next]](02-quickstart-docker.md) [curl]: https://curl.se/docs/manual.html [Dart SDK]: https://dart.dev/get-dart +[Installing and using dartfn]: 00-install-dartfn.md [Request]: https://pub.dev/documentation/shelf/latest/shelf/Request-class.html [Response]: https://pub.dev/documentation/shelf/latest/shelf/Response-class.html [Shelf]: https://pub.dev/packages/shelf diff --git a/docs/quickstarts/02-quickstart-docker.md b/docs/quickstarts/02-quickstart-docker.md index dc8d307a..682f8a89 100644 --- a/docs/quickstarts/02-quickstart-docker.md +++ b/docs/quickstarts/02-quickstart-docker.md @@ -13,8 +13,12 @@ environment. ## Get a copy of the `hello` example -Clone this repo or download a [zip] archive and extract the contents. Change -directory to `examples/hello`. +You can either + +* Run `dartfn` to create a new project using the `helloworld` generator (see + [Installing and using dartfn]) +* Clone this repo or download a [zip] archive and extract the contents + * Change directory to `examples/hello`. ## Build a Docker image @@ -203,4 +207,5 @@ docker image rm hellofunc # remove the image [docker]: https://docs.docker.com/get-docker/ +[Installing and using dartfn]: 00-install-dartfn.md [zip]: https://github.com/GoogleCloudPlatform/functions-framework-dart/archive/main.zip diff --git a/docs/quickstarts/03-quickstart-cloudrun.md b/docs/quickstarts/03-quickstart-cloudrun.md index 88d0cf20..92eb089e 100644 --- a/docs/quickstarts/03-quickstart-cloudrun.md +++ b/docs/quickstarts/03-quickstart-cloudrun.md @@ -46,8 +46,10 @@ Updated property [core/project]. ## Get a copy of the `hello` example -Clone this repo or download a [zip] archive and extract the contents. Change -directory to `examples/hello`. +* Run `dartfn` to create a new project using the `helloworld` generator (see + [Installing and using dartfn]) +* Clone this repo or download a [zip] archive and extract the contents + * Change directory to `examples/hello`. ## Build and deploy with a single command @@ -164,6 +166,7 @@ the [Manage resources] page. [gcloud]: https://cloud.google.com/sdk/docs/install [Google Cloud]: https://cloud.google.com/gcp [incur charges]: https://cloud.google.com/container-registry/pricing +[Installing and using dartfn]: 00-install-dartfn.md [Manage resources]: https://console.cloud.google.com/iam-admin/projects [project selector]: https://console.cloud.google.com/projectselector2/home/dashboard [quickstart]: https://cloud.google.com/sdk/docs/quickstart diff --git a/functions_framework_tool/README.md b/functions_framework_tool/README.md index 483e12fb..2205c0c3 100644 --- a/functions_framework_tool/README.md +++ b/functions_framework_tool/README.md @@ -7,9 +7,9 @@ In this early iteration, a CLI tool (`dartfn`) is provided with a `generate` command for scaffolding new projects into an empty directory. Three initial generator templates are available: -* helloworld - a basic HTTP handler function -* json - a simple function handler that accepts and sends JSON -* cloudevent - a simple cloudevent function handler +- helloworld - a basic HTTP handler function +- json - a simple function handler that accepts and sends JSON +- cloudevent - a simple cloudevent function handler To install the `dartfn` tool on your machine, run the following command: @@ -123,4 +123,3 @@ Output ```text 0.3.1 ``` -