Programming With Rust — Part Eighteen: Let’s Build A Library

We are now in a position to do something with an incoming HTTP Request, but what ?

HTTP is a versatile protocol, but a protocol is all it is. What a GET Request, for example, should actually get and how is up for grabs.

Rather than hardwire it for one implementation of GET, or POST or what have you, what we can do is turn httpd into a ‘framework’ which just deals with the protocol part and leave the semantics to the user of the framework.

The first step is to turn our executable into a library.

1.0 A Brief Introduction To Rust Attributes

Rust Attributes are a form of metadata which can be associated with crates and items.

An Attribute declaration is defined like this

    attributes_decl : ’#’ ’[’ attributes ’]’ [ ';' ] ? ; 

    attributes      : attribute [ ’,’ attributes ]* 
    
    attribute       : ident [ ’=’ literal | ’(’ attributes ’)’ ] ? ;

An Attribute declaration applies to the item it precedes unless the declaration is terminated with a semi-colon (;). In this case it applies to the entity in which it is contained.

Currently it is only possible to specify pre-defined Attributes.

2.0 Crate Files And Attributes

We can use the crate_type attribute to specify the type of the binary crate that should be built.

For example, if we include this crate_type Attribute declaration in a crate file

    #[crate_type = "lib"];

then the binary crate built from the crate file will be a library.

The default is bin which is why none of the earlier versions of httpd.rc needed to specify a crate_type attribute.

The name of the library and its version can be specified using the link attribute, like so

    #[link(name = "httpd", vers = "0.6")];

3.0 Modified Source Files

The only existing file we need to change is the crate file, httpd.rc

We need to add the appropriate crate_type and link attributes and remove the main function definition.

We also need to make public those modules that a user of the framework may need to access.

3.1 httpd.rc

// httpd.rc

// Crate file httpd v0.6

#[crate_type = "lib"];

#[link(name = "httpd", vers = "0.6")];


extern mod std;

pub mod HTTP;
pub mod headers;
pub mod request;
pub mod response;
pub mod server;

mod buffer;
mod writer;

4.0 A New Crate: httpd_main

For testing purposes we need a new executable that will link against our new library and initially at least, just run the server as before.

4.1 httpd_main.rc

// httpd_main.rc


extern mod httpd;

use httpd::server;

static PORT: uint = 3534;

static IPV4_LOOPBACK: &'static str = "127.0.0.1";

fn main()
{	
    server::run(IPV4_LOOPBACK, PORT);
}

5.0 Building The Library

We build the library by compiling the crate file as usual

    rustc httpd.rc

This produces a Mac OS X dynamic library

    libhttpd-94839cbfe144198-0.6.dylib

6.0 Building The Executable

We build the executable by compiling its crate file but in this case we need to tell the compiler where the library is using the -L flag like so

    rustc -L . httpd_main.rc

---

Copyright (c) 2013 By Simon Lewis. All Rights Reserved.

Unauthorized use and/or duplication of this material without express and written permission from this blog’s author and owner Simon Lewis is strictly prohibited.

Excerpts and links may be used, provided that full and clear credit is given to Simon Lewis and justanapplication.wordpress.com with appropriate and specific direction to the original content.