From db18647cb32603daae1ca9f9468a81453a9c71cc Mon Sep 17 00:00:00 2001 From: The-EDev Date: Thu, 30 Sep 2021 01:43:50 +0300 Subject: [PATCH] Added updated setup instructions (kept old instructions as "legacy") --- .../{setup.md => setup/legacy.md} | 13 ++- docs/getting_started/setup/linux.md | 79 +++++++++++++++++++ docs/getting_started/setup/macos.md | 57 +++++++++++++ docs/getting_started/setup/windows.md | 22 ++++++ docs/guides/routes.md | 4 + mkdocs.yml | 6 +- 6 files changed, 173 insertions(+), 8 deletions(-) rename docs/getting_started/{setup.md => setup/legacy.md} (93%) create mode 100644 docs/getting_started/setup/linux.md create mode 100644 docs/getting_started/setup/macos.md create mode 100644 docs/getting_started/setup/windows.md diff --git a/docs/getting_started/setup.md b/docs/getting_started/setup/legacy.md similarity index 93% rename from docs/getting_started/setup.md rename to docs/getting_started/setup/legacy.md index 8b6eb47f6..64f527362 100644 --- a/docs/getting_started/setup.md +++ b/docs/getting_started/setup/legacy.md @@ -1,16 +1,12 @@ -This page explains how to set Crow up for use with your project. +This page explains how to set Crow up for use with your project (***For versions 0.3+2 and lower***). ##Requirements - - C++ compiler with C++14 support. + - C++ compiler with C++11 support. - Crow's CI uses g++-9.3 and clang-7.0 running on AMD64 (x86_64) and ARM64v8 - - boost library (1.70 or later). + - boost library (1.64 or later). - **(optional)** ZLib for HTTP Compression. - **(optional)** CMake and Python3 to build tests and/or examples. - - **(optional)** Linking with jemalloc/tcmalloc is recommended for speed. -!!!note - - While using Boost 1.70 or later is recommended, it may be possible to compile a Crow application with version 1.64

@@ -22,6 +18,9 @@ This page explains how to set Crow up for use with your project. ###Ubuntu `sudo apt-get install build-essential libboost-all-dev` +###Arch +`sudo pacman -S python boost boost-libs` + ###Non Debian based GNU/Linux Use your package manager to install the following: - GCC and G++ (or Clang and Clang++) diff --git a/docs/getting_started/setup/linux.md b/docs/getting_started/setup/linux.md new file mode 100644 index 000000000..2875fa189 --- /dev/null +++ b/docs/getting_started/setup/linux.md @@ -0,0 +1,79 @@ +Here's how you can install Crow on your favorite GNU/Linux distro. +# Getting Crow + +## Requirements + - C++ compiler with at least C++11 support. + - boost library & development headers (1.64 or later). + - **(optional)** ZLib for HTTP Compression. + - **(optional)** OpenSSL for HTTPS support. + - **(optional)** CMake and Python3 to build tests and/or examples. +!!!note + + Crow's CI uses `g++-9.3` and `clang-7.0` running on AMD64 (x86_64) and ARM64v8 architectures. + + +

+ +## Using a package Manager +You can install Crow on GNU/Linux as a pre-made package +=== "Debian/Ubuntu" + + Simply download Crow's `.deb` file from the [release section](https://github.com/CrowCpp/Crow/releases/latest) and Install it. + +=== "Arch" + + Crow is available for pacman through AUR, you only need to run `pacman -S crow` + + +

+## Release package +Crow provides an archive containing the framework and CMake files, just copy the `include` folder to `/usr/local/include` and `lib` folder to `/usr/local/lib`.

+You can also download the `crow_all.h` file and simply include that into your project. +

+## Installing from source +### Using CMake +1. Download Crow's source code (Either through github's UI or by using
`git clone https://github.com/CrowCpp/Crow.git`). +2. Run `mkdir build` inside of crow's source directory. +3. Navigate to the new "build" directory and run the following:
+`cmake .. -DCROW_BUILD_EXAMPLES=OFF -DCROW_BUILD_TESTS=OFF` +4. Run `make install`. +!!!note + + You can ignore `-DCROW_BUILD_EXAMPLES=OFF -DCROW_BUILD_TESTS=OFF` if you want to build the Examples and Unit Tests. +
+### Manually +Crow can be installed manually on your Linux computer. +#### Multiple header files +=== "Project Only" + + Copy Crow's `include` directory to your project's `include` directory. + +=== "System wide" + + Copy Crow's `include` directory to the `/usr/local/include` directory. + +#### Single header (crow_all.h) +!!!warning + + `crow_all.h` is recommended only for small, possibly single source file projects, and ideally should not be installed on your system. +navigate to the `scripts` directory and run `./merge_all.py ../include crow_all.h`. This will generate a `crow_all.h` file that you can use in your projects. +!!!note + + You can also include or exclude middlewares from your `crow_all.h` by using `-i` or `-e` followed by the middleware header file names separated by a comma (e.g. `merge_all.py ../include crow_all.h -e cookie_parser` to exclude the cookie parser middleware). +# Compiling your project +## Using CMake +In order to get your CMake project to work with Crow, all you need are the following lines in your CMakeLists.txt: +``` +find_package(Crow) +target_link_libraries(your_project PUBLIC Crow::Crow) +``` +From there CMake should handle compiling and linking your project. +## Directly using a compiler +All you need to do is run the following command: +``` +g++ main.cpp -lpthread +``` +You can use arguments like `-DCROW_ENABLE_DEBUG`, `-DCROW_ENABLE_COMPRESSION -lz` for HTTP Compression, or `-DCROW_ENABLE_SSL -lssl` for HTTPS support, or even replace g++ with clang++. +!!!warning + + If you're using a version of boost prior to 1.69, you'll need to add the argument `-lboost_system` in order for you Crow application to compile correctly. diff --git a/docs/getting_started/setup/macos.md b/docs/getting_started/setup/macos.md new file mode 100644 index 000000000..fcc110988 --- /dev/null +++ b/docs/getting_started/setup/macos.md @@ -0,0 +1,57 @@ +Here's how you can install Crow on your Mac. +# Getting Crow +## From a [release](https://github.com/CrowCpp/Crow/releases) +### Archive +Crow provides an archive containing the framework and CMake files, You will only need the `include` folder inside that archive. +### Single header file +You can also download the `crow_all.h` file which replaces the `include` folder. + +## From Source +To get Crow from source, you only need to download the repository (as a `.zip` or through `git clone https://github.com/CrowCpp/Crow.git`). +### include folder +Once you've downloaded Crow's source code, you only need to take the `include` folder. +### Single header file +You can generate your own single header file by using navigating to the `scripts` folder with your terminal and running the following command: +``` +python3 merge_all.py ../include crow_all.h +``` +This will generate a `crow_all.h` file which you can use in the following steps +!!!warning + + `crow_all.h` is recommended only for small, possibly single source file projects. For larger projects, it is advised to use the multi-header version. + + +# Setting up your Crow project +## Using XCode +1. Download and install [Homebrew](https://brew.sh). +2. Run `brew install boost` in your terminal. +3. Create a new XCode project (macOS -> Command Line Tool). +4. Change the following project settings: + + === "Multiple Headers" + + 1. Add header search paths for crow's include folder and boost's folder (`/usr/local/include`, `/usr/local/Cellar/boost/include`, and where you placed Crow's `include` folder) + 2. Add linker flags (`-lpthread` and `-lboost_system` if you're running an old version of boost) + + === "Single Header" + + 1. Place `crow_all.h` inside your project folder and add it to the project in XCode (you need to use the File -> ) + 2. Add header search paths for boost's folder (`/usr/local/include`, and `/usr/local/Cellar/boost/include`) + 3. Add linker flags (`-lpthread` and `-lboost_system` if you're running an old version of boost) + +5. Write your Crow application in `main.cpp` (something like the Hello World example will work). +6. Press `▶` to compile and run your Crow application. + + +# Building Crow's tests/examples +1. Download and install [Homebrew](https://brew.sh). +2. Run `brew install cmake boost` in your terminal. +3. Get Crow's source code (the entire source code). +3. Run the following Commands: + 1. `mkdir build` + 2. `cd build` + 3. `cmake ..` + 4. `make -j12` +!!!note + + You can add options like `-DCROW_ENABLE_SSL`, `-DCROW_ENABLE_COMPRESSION`, or `-DCROW_AMALGAMATE` to `3.c` to build their tests/examples. \ No newline at end of file diff --git a/docs/getting_started/setup/windows.md b/docs/getting_started/setup/windows.md new file mode 100644 index 000000000..f58c2b7c7 --- /dev/null +++ b/docs/getting_started/setup/windows.md @@ -0,0 +1,22 @@ +Here's how you can install Crow on your Windows machine. +# Getting and Compiling Crow +## Using A package manager +### VCPKG +Crow can be simply installed through VCPKG using the command `vcpkg install crow` + +## Manually (source or release) +### Microsoft Visual Studio 2019 and VCPKG +The following guide will use `example_with_all.cpp` as the Crow application for demonstration purposes. VCPKG will be used only to install Crow's dependencies. + +1. Generate `crow_all.h` by navigating to the `scripts` folder and running `python3 merge_all.py ..\include crow_all.h`. +2. `git clone https://github.com/microsoft/vcpkg.git` +3. `.\vcpkg\bootstrap-vcpkg.bat` +4. `.\vcpkg\vcpkg integrate install` +5. Create empty Visual Studio project. +6. In solution explorer, right click the name of your project then click `Open Folder in File Explorer`. +7. Copy `crow_all.h`, `example_with_all.cpp`, `vcpkg.json` to opened folder. +8. Add `crow_all.h` to `Header Files` and `example_with_all.cpp` to `Source Files`. +9. In solution explorer, right click the name of your project then click `Properties`. +10. Under `vcpkg`, set `Use Vcpkg Manifest` to `Yes` and `Additional Options` to `--feature-flags="versions"`. +11. Set `Debug/Release` and `x64/x86`. +12. Run. diff --git a/docs/guides/routes.md b/docs/guides/routes.md index e7fe72435..3fb744036 100644 --- a/docs/guides/routes.md +++ b/docs/guides/routes.md @@ -76,3 +76,7 @@ class a : public crow::returnable ##Catchall routes **Introduced in: `v0.3`**

By default, any request that Crow can't find a route for will return a simple 404 response. You can change that to return a default route using the `CROW_CATCHALL_ROUTE(app)` macro. Defining it is identical to a normal route, even when it comes to the `const crow::request&` and `crow::response&` parameters being optional. +!!!note + + For versions higher than 0.3 (excluding patches), Catchall routes handle 404 and 405 responses. The default response will contain the code 404 or 405. + diff --git a/mkdocs.yml b/mkdocs.yml index 968324c90..bb213d1c1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -28,7 +28,11 @@ markdown_extensions: nav: - Home: index.md - Getting Started: - - Setup: getting_started/setup.md + - Setup: + - Linux: getting_started/setup/linux.md + - MacOS: getting_started/setup/macos.md + - Windows: getting_started/setup/windows.md + - Legacy: getting_started/setup/legacy.md - Your First Application: getting_started/your_first_application.md - Guides: - Different parts of Crow: