docs/beginners-guide.md

   1 Beginners Guide to Link
   2 =======================
   3
   4 >
   5 > Author: Ariston Lorenzo <me@ariston.dev>
   6 > <br>
   7 > Last Modified: April 13, 2023
   8 >
   9
  10 Introduction
  11 ------------
  12 Link is a web server library built with a focus of speed for C++. Link is meant
  13 to be a relatively easy framework to use and is considered the *ExpressJS* for
  14 C++ developers.
  15
  16 A New Project (with linkproj)
  17 -----------------------------
  18 Once you have installed Link, you can clone the [aristonl/linkproj](https://github.com/aristonl/linkproj)
  19 repository which is meant to be a simple template you can use to quickly setup
  20 a Link-based project. To build, all you need to do is:
  21
  22         mkdir build && cd build
  23         cmake ..
  24         make
  25         ./website
  26
  27 Or you can also use ninja like so:
  28
  29         mkdir build && cd build
  30         cmake -GNinja ..
  31         ninja
  32         ./website
  33
  34 *linkproj* will run on port 3000 by default. You can start editing your site in
  35 `www/` and handle all C++ related code in `src/`.
  36
  37 A New Project (from scratch)
  38 ----------------------------
  39 Once you have installed Link, create a new folder where your website
  40 will be stored. Create a new .cpp file in the root of the project (or create a separate
  41 src/ directory). The following code is just a simple "Hello, World!" site.
  42
  43 ```cpp
  44 #include <Link.hpp>
  45 #include <iostream>
  46 #include <openssl/ssl.h>
  47 #include <thread>
  48
  49 Link::Server server(8080) /* Set the port */
  50
  51 int main(int argc, char **argv)
  52 {
  53         /* Handle requests for http://localhost:8080/ */
  54         server.Get("/", [](Link::Request* req, Link::Response* res) {
  55                 /* Set the HTTP Header */
  56                 res->SetHeader("Content-Type", "text/html; charset=UTF-8");
  57                 /* Send the actual content of the page */
  58                 res->SetBody("<h1>Hello, World!</h1>");
  59         });
  60
  61         /* Start the server */
  62         std::cout << "Server started on port 8080." << '\n';
  63         server.Start();
  64
  65         return 0;
  66 }
  67 ```
  68
  69 To build the web server, you can either use Make (GNU or BSD) or CMake. The
  70 following is a CMake example:
  71
  72         cmake_minimum_required(VERSION 3.16)
  73         project(website C CXX)
  74
  75         # Set include directory for OpenSSL on Mac
  76         include_directories(/opt/homebrew/opt/openssl@3/include)
  77
  78         set(cpp_src main.cpp)
  79
  80         add_executable(website ${cpp_src})
  81         target_compile_features(website PUBLIC cxx_std_17)
  82         set(CMAKE_CXX_FLAGS "-fpic -pthread")
  83
  84         target_link_libraries(website PRIVATE link)
  85
  86 If you plan to use CMake, it is best to use it in tandem with Ninja. Here's a
  87 Make example:
  88
  89         PROG=website
  90
  91         CXXFLAGS=-g -O2
  92         CXX=g++
  93         LIBS=-llink
  94
  95         all: $(PROG)
  96
  97         $(PROG): main.o
  98                 $(CXX) -o $@ main.o $(LIBS)
  99
 100         .cpp.o:
 101                 $(CXX) $(CFLAGS) -c $*.cpp
 102
 103         main.o: main.cpp
 104
 105 Once the `website` executable is built, run it using `./website` and open your
 106 browser to http://localhost:8080 (or any other port you may have set it to). It should show "Hello, World!".
 107
 108 <br>
 109
 110 Obviously, we don't want to put all the HTML in the C++ file but instead have it
 111 in a separate HTML file that we can call. To be able to do this, you can modify your source code like so:
 112
 113 ```cpp
 114 #include <fstream>
 115
 116 int main(int argc, char **argv)
 117 {
 118         server.Get("/", [](Link::Request* req, Link::Response* res) {
 119                 res->SetHeader("Content-Type", "text/html; charset=UTF-8");
 120                 std::ifstream file("index.html");
 121                 std::string content((std::istreambuf_iterator<char>(file)),
 122                         std::istreambuf_iterator<char>());
 123                 res->SetBody(content);
 124         });
 125
 126         std::cout << "Server started on port 8080." << '\n';
 127         server.Start();
 128
 129         return 0;
 130 }
 131 ```
 132
 133 Then you can create `index.html` and edit it like a normal HTML file.
 134
 135 > -----------------------------------------------------------------------------
 136 >
 137 > **NOTE**: *When calling index.html with `ifstream`, the location of index.html
 138 > should be entered as the relative location from the executable. For example,
 139 > if your file tree looks like this:*
 140 >
 141 > ```
 142 >    .
 143 >       |- bin
 144 >       |  |- website
 145 >       |- www
 146 >          |- index.html
 147 > ```
 148 >
 149 > *The location of index.html should be filled in like so:*
 150 > ```cpp
 151 > std::ifstream file("../www/index.html");
 152 > ```
 153 >
 154 > -----------------------------------------------------------------------------
 155
 156 You can also serve static files by pointing `server.SetStaticPages` to the folder
 157 it's located in (usually `static/` or `public/`) like so:
 158
 159 ```cpp
 160 int main(int argc, char **argv)
 161 {
 162         server.SetStaticPages("public/");
 163
 164         /* rest of the code here... */
 165 }
 166 ```
 167
 168 > -----------------------------------------------------------------------------
 169 >
 170 > **NOTE**: *The location of the folder must also be specified as its relative
 171 > location to the executable.*
 172 >
 173 > -----------------------------------------------------------------------------
 174
 175 The files can be accessed with just `http://localhost:8080/` with the path
 176 being just the directory structure of the `public/`
 177 folder. For example, if this is your `public/`
 178 folder structure:
 179
 180         public
 181         |- css
 182         |  |- index.css
 183         |  |- fonts.css
 184         |- js
 185            |- index.js
 186
 187 And you want to access `index.css`, the URL will be:
 188 `http://localhost:8080/css/index.css`, and vice versa.