Browse Source

start working on guide

master
Nikolay Kim 2 years ago
parent
commit
599f3c26e0
9 changed files with 141 additions and 8 deletions
  1. +2
    -3
      .gitignore
  2. +9
    -0
      .travis.yml
  3. +1
    -1
      build.rs
  4. +3
    -3
      examples/basic.rs
  5. +3
    -0
      guide/book.toml
  6. +4
    -0
      guide/src/SUMMARY.md
  7. +34
    -0
      guide/src/qs_1.md
  8. +85
    -0
      guide/src/qs_2.md
  9. +0
    -1
      src/prelude.rs

+ 2
- 3
.gitignore View File

@@ -1,7 +1,7 @@
target/
Cargo.lock
target/
guide/build/
/gh-pages
__pycache__

*.so
*.out
@@ -9,7 +9,6 @@ __pycache__
*.pid
*.sock
*~
*.egg-info/

# These are backup files generated by rustfmt
**/*.rs.bk

+ 9
- 0
.travis.yml View File

@@ -29,6 +29,13 @@ before_script:

script:
- USE_SKEPTIC=1 cargo test --features=alpn

# Build without unstable flag
- cargo build

# Test examples in guide.
- rustdoc --test guide/src/qs_2.md -L target/debug -L target/debug/deps

- |
if [[ "$TRAVIS_RUST_VERSION" == "nightly" && $CLIPPY ]]; then
cargo clippy
@@ -40,6 +47,8 @@ after_success:
if [[ "$TRAVIS_OS_NAME" == "linux" && "$TRAVIS_PULL_REQUEST" = "false" && "$TRAVIS_BRANCH" == "master" && "$TRAVIS_RUST_VERSION" == "nightly" ]]; then
cargo doc --features alpn --no-deps &&
echo "<meta http-equiv=refresh content=0;url=os_balloon/index.html>" > target/doc/index.html &&
cargo install mdbook &&
cd guide && mdbook build -d ../target/doc/guide && cd .. &&
git clone https://github.com/davisp/ghp-import.git &&
./ghp-import/ghp_import.py -n -p -f -m "Documentation upload" -r https://"$GH_TOKEN"@github.com/"$TRAVIS_REPO_SLUG.git" target/doc &&
echo "Uploaded documentation"


+ 1
- 1
build.rs View File

@@ -8,7 +8,7 @@ use std::{env, fs};
fn main() {
if env::var("USE_SKEPTIC").is_ok() {
// generates doc tests for `README.md`.
skeptic::generate_doc_tests(&["README.md"]);
skeptic::generate_doc_tests(&["README.md", "guide/src/qs_2.md"]);
} else {
let f = env::var("OUT_DIR").unwrap() + "/skeptic-tests.rs";
let _ = fs::File::create(f);


+ 3
- 3
examples/basic.rs View File

@@ -11,7 +11,7 @@ use actix_web::error::{Error, Result};
use actix_web::middlewares::RequestSession;
use futures::stream::{once, Once};

/// somple handle
/// simple handler
fn index(mut req: HttpRequest) -> Result<HttpResponse> {
println!("{:?}", req);
if let Ok(ch) = req.payload_mut().readany() {
@@ -31,7 +31,7 @@ fn index(mut req: HttpRequest) -> Result<HttpResponse> {
Ok(httpcodes::HTTPOk.into())
}

/// somple handle
/// async handler
fn index_async(req: HttpRequest) -> Once<actix_web::Frame, Error>
{
println!("{:?}", req);
@@ -43,7 +43,7 @@ fn index_async(req: HttpRequest) -> Once<actix_web::Frame, Error>
.into()))
}

/// handle with path parameters like `/user/{name}/`
/// handler with path parameters like `/user/{name}/`
fn with_param(req: HttpRequest) -> Result<HttpResponse>
{
println!("{:?}", req);


+ 3
- 0
guide/book.toml View File

@@ -0,0 +1,3 @@
title = "Actix web"
description = "Actix web framework guide"
author = "Actix Project and Contributors"

+ 4
- 0
guide/src/SUMMARY.md View File

@@ -0,0 +1,4 @@
# Summary

[Quickstart](./qs_1.md)
- [Getting Started](./qs_2.md)

+ 34
- 0
guide/src/qs_1.md View File

@@ -0,0 +1,34 @@
# Quickstart

Before you can start writing a actix web application, you’ll need a version of Rust installed.
We recommend you use rustup to install or configure such a version.

## Install Rust

Before we begin, we need to install Rust using the [rustup](https://www.rustup.rs/) installer:

```bash
curl https://sh.rustup.rs -sSf | sh
```

If you already have rustup installed, run this command to ensure you have the latest version of Rust:

```bash
rustup update
```

Actix web framework requies rust version 1.20 and up.

## Running Examples

The fastest way to start experimenting with actix web is to clone the actix web repository
and run the included examples in the examples/ directory. The following set of
commands runs the `basic` example:

```bash
git clone https://github.com/actix/actix-web
cd actix-web
cargo run --example basic
```

Check `examples/` directory for more examples.

+ 85
- 0
guide/src/qs_2.md View File

@@ -0,0 +1,85 @@
# Getting Started

Let’s create and run our first actix web application. We’ll create a new Cargo project
that depends on actix web and then run the application.

In previous section we already installed required rust version. Now let's create new cargo projects.

## Hello, world!

Let’s write our first actix web application! Start by creating a new binary-based
Cargo project and changing into the new directory:

```bash
cargo new hello-world --bin
cd hello-world
```

Now, add actix and actix web as dependencies of your project by ensuring your Cargo.toml
contains the following:

```toml
[dependencies]
actix = "0.3"
actix-web = { git = "https://github.com/actix/actix-web" }
```

In order to implement a web server, first we need to create a request handler.

A request handler is a function that accepts a `HttpRequest` instance as its only parameter
and returns a `HttpResponse` instance or actor that uses `HttpContext` as an actor's context::

```rust,ignore
extern crate actix_web;
use actix_web::prelude::*;

fn index(req: HttpRequest) -> Result<HttpResponse> {
Ok(httpcodes::HTTPOk.with_body("Hello world!"))
}
```

Next, create an `Application` instance and register the
request handler with the application's `resource` on a particular *HTTP method* and *path*::

```rust,ignore
let app = Application::default("/")
.resource("/", |r| r.handler(Method::GET, index)
.finish()
```

After that, application instance can be used with `HttpServer` to listen for incoming
connections:

```rust,ignore
HttpServer::new(app).serve::<_, ()>("127.0.0.1:8088");
```

That's it. Now, compile and run the program with cargo run.
Head over to ``http://localhost:8088/`` to see the results.

Here is full source of main.rs file:

```rust
extern crate actix;
extern crate actix_web;
use actix_web::prelude::*;

fn index(req: HttpRequest) -> Result<HttpResponse> {
Ok(httpcodes::HTTPOk.with_body("Hello world!"))
}

fn main() {
let sys = actix::System::new("example");

HttpServer::new(
Application::default("/")
.resource("/", |r| r.handler(Method::GET, index)))
.serve::<_, ()>("127.0.0.1:8088").unwrap();

println!("Started http server: 127.0.0.1:8088");
// do not copy this line
actix::Arbiter::system().send(actix::msgs::SystemExit(0));

let _ = sys.run();
}
```

+ 0
- 1
src/prelude.rs View File

@@ -1,7 +1,6 @@
//! The `actix-web` prelude

pub use super::*;

pub use error::*;
pub use application::ApplicationBuilder;
pub use httpresponse::HttpResponseBuilder;


Loading…
Cancel
Save