# Resource builder for httpstorm

### Convert resource files to source code for integration in C++ applications

#### Description
This tool helps application authors integrate resource files in the binary.
When used with a directory, all files are included in a searchable catalogue,
preserving the directory structure. A binary-search API is available to locate
resources during runtime. Resources can also be referenced statically in the code.
Possible use cases include a web server, where the entire web site is built into
the binary. Or saving a resource to the filesystem with full path basted on the
original resource path.

#### Command line options
|      | `g_resource_builder [-a] [-f] [-h] <target.cpp> [-d dir] <source 1-n>` |
| ---- | :--------------------------------------------------------------------- |
| `-q` | quiet |
| `-a` | append |
| `-b` | use big endianess output: useful for cross-compiling when the host and target use different endianess |
| `-d` | change directory to dir |
| `-f` | use flat labels, without this the directory tree is preserved |
| `-h` | use hierarchy structure, implies `-f` |

#### Sample use
```powershell
g_resource_builder -h src/g_resource_data.cpp -d res .  # UNIX
g_resource_builder -h src\g_resource_data.cpp -d res *  # Windows
```

#### List of ignored files
```
.DS_Store .aps .rc resource.h
```

#### [g_resource class API](../../../lib.git#features-of-g_api)
For each resource file, an instance of the `g_resource` class is created.
The class is defined in `lib/g_api/src/g_resource.h`, and provides the
following properties:
```C++
const wchar_t * const name_w;           // L"httpstorm.ini"
const char * const path_root_a;         // "/etc/httpstorm/httpstorm.ini"
const char * const path_a;              //  "etc/httpstorm/httpstorm.ini"
const char * const path_short_a;        //      "httpstorm/httpstorm.ini"
const char * const name_a;              //                "httpstorm.ini"
const HTTP_CONTENT_TYPE type;           // HTTP_CONTENT_TYPE_TEXT_PLAIN
const TXT_ENCODING encoding;            // TXT_ENCODING_ANSI
const uint32_t size_data;               // 1275  size of the resource
const uint32_t size_text_a;             // 1275  size past the unicode marker (if any)
const uint32_t size_text_u;             // 637   size in char16_t characters
const char * const data;                // resource content

union
{
  const char     * const text_a;
  const char16_t * const text_u;        // httpstorm_ini.data + 0
};                                      // text content past the unicode marker (if any)

const char modified  [G_DATE_GMT_SIZE]; // "Mon, 21 Feb 2022 0:36:30 GMT"
const char modified_l[G_DATE_GMT_SIZE]; // "mon, 21 feb 2022 0:36:30 gmt"
```

The class is designed to provide access to all commonly used information directly.

| Name           | Description |
| -------------- | ----------- |
| `name_w`       | file name as a string of `wchar_t` |
| `name_a`       | file name as a string of `char` |
| `path_root_a`  | full path |
| `path_a`       | full path excluding the leading `/` character |
| `path_short_a` | also ommits the root directory |
| `type`         | HTTP content type defined in `g_api/src/g_http_content_type.h` |
| `encoding`     | can be `ANSI` `UTF8` `UTF16LE` or `UTF16BE`, defined in `g_api/src/g_txt_encoding.h` |
| `size_data`    | size of the resource |
| `size_text_a`  | size past the unicode marker (if any) |
| `size_text_u`  | size in `char16_t` characters |
| `data`         | resource content |
| `text_a`       | text content past the unicode marker (if any) as `char *` |
| `text_u`       | text content past the unicode marker (if any) as `char16_t *` |
| `modified`     | time of last monitication |
| `modified_l`   | time of last monitication in lower case |


#### Referencing resources
Say we have three files inside `res/etc/httpstorm`. After generating resources
in the `res` directory, the following namespace structure is generated:
```C++
namespace g_res
{
  namespace etc
  {
    namespace httpstorm
    {
      extern const g_resource httpstorm_ini;
      extern const g_resource httpstorm_iphone_ini;
      extern const g_resource httpstorm_openwrt_ini;
    }
  }
}
```

To access `/etc/httpstorm/httpstorm_ini`, use
`g_res::etc::httpstorm::httpstorm_ini` in your code.
The array with all resources is accessible as `const g_resource * g_res::all[]`.
The array with all resources inside `etc` is accessible as
`const g_resource * g_res::etc::all[]`.
The following search against `path_short_a` can be performed to locate a resource
in `etc` at runtime:
```C++
// returns a pointer to `g_res::etc::httpstorm::httpstorm_ini`
const g_resource * p_res = g_res::g_bin_search_path_short_a(
  g_res::etc::all,              // const g_resource * const * arr
  g_res::etc::all_length,       // size_t length    // length of arr
  "httpstorm/httpstorm.ini"     // const char * str // match against path_short_a
);
```

Before searching resources for the first time, the catalogue should be sorted
by calling `g_res::sort_all();`.


#### Supported Platforms
☂︎ Apple iOS, macOS  
☂︎ FreeBSD  
☂︎ Linux, OpenWRT  
☂︎ Windows  


#### [Prerequisites and build instructions](../../../lib.git#Prerequisites)


#### © 2019-2023 Georgi Valkov
https://httpstorm.com/download/g_resource_builder/