From 05b38de4adbdac946df5f9acfaaee4ef22ce3166 Mon Sep 17 00:00:00 2001 From: lcsmuller Date: Fri, 7 Jan 2022 12:10:26 -0300 Subject: [PATCH 1/3] docs(SAIPHC.md): delete it --- docs/SAIPHC.md | 80 -------------------------------------------------- 1 file changed, 80 deletions(-) delete mode 100644 docs/SAIPHC.md diff --git a/docs/SAIPHC.md b/docs/SAIPHC.md deleted file mode 100644 index d2f160cd7..000000000 --- a/docs/SAIPHC.md +++ /dev/null @@ -1,80 +0,0 @@ -# Saiph-C - -[The Saiph-C SDK](https://www.cee.studio/get_sdk.html) is a compiler for C and C++ programs that allows users to diagnose segmentation faults in an easy and simple manner. - -## Installing and Using Saiph-C for Orca - -Please run the following commands as *a normal user* (NOT ROOT). - -Follow the installation steps [here](https://www.cee.studio/get_sdk.html). After this, there are some additional steps required to compile Orca: - -1. Download the additional libraries for Saiph-C from [here](https://github.com/cee-studio/packages) using the following command: - ``` - git clone https://github.com/cee-studio/packages.git - ``` -2. For Orca, use these commands inside the above `packages` folder to install the libraries instead: - ``` - CC=sfc make bearssl curl - ./install.sh - ``` -3. To build Orca: - ``` - cd orca - CC=sfc make - ``` - - -# Using Saiph-C to Diagnose Segfaults - -As of the current build of Orca, [Saiph-C](https://www.cee.studio/get_sdk.html) can be used to compile any bots made and will give easy-to-read instructions. - -Running the bot after doing [Using Saiph-C](#installing-and-using-saiph-c-for-orca) should be the same as any other C program. However, Saiph-C provides diagnostic information in the case of incorrect memory access. - -## Parts of a Saiph-C error - -Examples of Saiph-C errors are shown [here](https://www.cee.studio/benefits.html). -As Saiph-C covers many types of memory access errors/warnings, messages are varied, but they should have three parts: [the memory error type](#memory-error-type), [the general information](#general-information), [and the stack trace](#stack-trace). - -### Memory Error Type - -#### Example: -``` -Memory access error: writing to the outside of a memory block; abort! -``` - -The Memory Error Type Block of a Saiph-C message is the first part of a message and defines the type of memory access violation that has occured; it usually has this format: - -``` -Memory access : -; - -``` - -Check [here](https://www.cee.studio/benefits.html) for a list of all the memory violation types. - -### General Information - -#### Example: -``` -# Writing 1 bytes to 0x929e010 may clobber other memory blocks. -# -# The memory-block-to-be-written (start:0x929e010, size:10 bytes) was allocated at -# file:/prog.c::10, 14 -# [libc-start-main] -# It has been freed at -# file:/prog.c::11, 3 -# [libc-start-main] -# The allocation/free locations could have been distorted by subsequent reuses. -``` - -The General Information Block of a Saiph-C message is the second part of a message and further specifies the memory violation that occurs. This can vary from memory violation to memory violation and can even be absent in specific ones. - -### Stack Trace - -#### Example: -``` -# Stack trace (most recent call first) of the read. -# [0] file:/prog.c::7, 3 -# [1] [libc-start-main] -``` -The Stack Trace portion of Saiph-C is the last part of a message and will give a stack trace of the functions that called the erroring line. This is pretty self-explainatory, but it should be noted that **the most recent call is the top-most function**. From 447dc801b8b2309d055e0f1cf8d924a3259a9cc5 Mon Sep 17 00:00:00 2001 From: lcsmuller Date: Fri, 7 Jan 2022 12:11:12 -0300 Subject: [PATCH 2/3] docs(INTERNALS.md): remove github references and list it it at README.md --- README.md | 2 +- docs/INTERNALS.md | 36 +++++++++++++++++++++--------------- 2 files changed, 22 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 2df0afc00..41e4264d0 100644 --- a/README.md +++ b/README.md @@ -203,7 +203,7 @@ Problems? Check out our [Discord Server](https://discord.gg/nBUqrWf). - [Building your first bot](docs/BUILDING_A_BOT.md) - [Contributing](docs/CONTRIBUTING.md) - +- [Internals](docs/INTERNALS.md) ## Contributing Check our [Contributing Guidelines](docs/CONTRIBUTING.md) to get started! If you are here for the Discord API, please check our [Discord API Roadmap](docs/DISCORD_ROADMAP.md). diff --git a/docs/INTERNALS.md b/docs/INTERNALS.md index 6cdd930cb..494346e91 100644 --- a/docs/INTERNALS.md +++ b/docs/INTERNALS.md @@ -5,24 +5,23 @@ # Introduction If you are interested in contributing with more than just coding, you found the -right place! The ultimate goal is to help you understand how Orca works internally, -and as a result, write your own API endpoint. +right place! The ultimate goal is to help you understand how Concord works internally, +and as a result, write your own API endpoint. Before starting make sure you have followed the [build instructions](../README.md#build-instructions)! -## About Orca +## About Concord -Orca is a collection of REST API wrappers that are written in C. Orca currently -covers the Discord API (and GitHub, Reddit, and Slack to some degree). +Concord is a Discord API wrappers written entirely in C. -# A Tour of Orca +# A Tour of Concord -While Orca is not complex, it is still a decently sized project. Navigating the +While Concord is not complex, it is still a decently sized project. Navigating the documentation may be confusing to new potential contributors when searching for certain things. This section aims to assist you with understanding each of the major folders and files. -## Orca Specs +## Concord Specs Wrapping an API object in C can quickly get overwhelming and repetitive, considering one have to address many things modern languages would take for granted, such as the @@ -31,7 +30,7 @@ for wrapping and generating API objects. - `specs/`: This is the folder we write our specs for code-generation, it contains multiple JSON templates that are parsed by `specs/specs-gen.c`. To generate code from - scratch simply run `make specs_gen`, the code will be placed inside of `specs-code/`. + scratch simply run `make specs_gen`, the code will be placed inside of `src/specs-code/`. ## Examples @@ -40,11 +39,16 @@ The `examples/` folder is where we place our up-to-date bot examples. When adding a new feature it is encouraged that the contributor writes an example bot to demonstrate said feature, as a sort of makeshift test for other users and developers. -## APIs source-code +## API source-code -`discord-*.c`, `github-*.c`, `reddit-*.c`, and `slack-*.c` are the source -files that handle all the logic behind their individual API wrapper. +The `src/` folder is where we place all of our Discord API wrapping logic. +## Common source-code + +The `common/` folder is where we place all of our generic logic, such as handling of the +WebSockets and REST protocols, threadpool management, etc. + + + +If you have any questions, feel free to join our [Discord server](https://discord.gg/Y7Xa6MA82v). From 9ed2edfaf41fe041999c9c9cd4215227aa5e9590 Mon Sep 17 00:00:00 2001 From: lcsmuller Date: Fri, 7 Jan 2022 12:11:28 -0300 Subject: [PATCH 3/3] wip: remove orca references --- docs/BUILDING_A_BOT.md | 40 ++++++++++++++++++++-------------------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/BUILDING_A_BOT.md b/docs/BUILDING_A_BOT.md index 73bfbb728..abba93019 100644 --- a/docs/BUILDING_A_BOT.md +++ b/docs/BUILDING_A_BOT.md @@ -80,21 +80,21 @@ You can also initialize it by providing the token directly to `discord_init()`: struct discord *client = discord_init(BOT_TOKEN); ``` -### [discord\_config\_init()](https://cee-studio.github.io/orca/apis/discord.html?highlight=set_on_command#c.discord_config_init) +### discord\_config\_init() `discord_config_init(char[])` : initialize the bot with a configuration file -Returns [struct discord](https://cee-studio.github.io/orca/apis/discord.html?highlight=set_on_command#c.discord): the bot client +Returns `struct discord`: the bot client | Member Parameters | Description | | :---------------- | :------------------------------ | | char[] | the name of the bot config file | -## [discord\_init()](https://cee-studio.github.io/orca/apis/discord.html?highlight=set_on_command#c.discord_init) +## discord\_init() `discord_init(char[])` : initialize the bot with a token -Returns [struct discord](https://cee-studio.github.io/orca/apis/discord.html?highlight=set_on_command#c.discord): the bot client +Returns `struct discord` the bot client | Member Parameters | Description | | :---------------- | :------------------- | @@ -110,32 +110,32 @@ discord_set_on_command(client, "pong", &on_pong); discord_run(client); ``` -### [discord\_set\_on\_ready()](https://cee-studio.github.io/orca/apis/discord.html?highlight=set_on_command#c.discord_set_on_ready) +### discord\_set\_on\_ready() `discord_set_on_ready(struct discord*, discord_on_idle*)`: calls `on_ready` callback when the connection is succesfully established -| Member Parameters | Description | -| :------------------------------------------------------------------------------------------- | :---------------------------------------------------- | -| [struct discord](https://cee-studio.github.io/orca/apis/discord.html#c.discord) | the client stucture | -| [discord\_on\_idle](https://cee-studio.github.io/orca/apis/discord.html#c.discord_idle_cb)\* | the callback to run when the READY event is triggered | +| Member Parameters | Description | +| :---------------------| :---------------------------------------------------- | +| `struct discord` | the client stucture | +| `discord\_on\_idle()` | the callback to run when the READY event is triggered | -### [discord\_set\_on\_command()](https://cee-studio.github.io/orca/apis/discord.html?highlight=set_on_command#c.discord_set_on_command) +### discord\_set\_on\_command() `discord_set_on_command(struct discord*, char[], discord_message_cb*)`: runs callback when a command prefix is detected on chat -| Member Parameters | Description | -| :------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------- | -| [struct discord](https://cee-studio.github.io/orca/apis/discord.html#c.discord) | the client stucture | -| char[] | The chat command expected to trigger a callback response | -| [discord\_on\_message](https://cee-studio.github.io/orca/apis/discord.html#c.discord_message_cb)\* | the message type function callback to run when its corresponding event is triggered | +| Member Parameters | Description | +| :----------------------| :---------------------------------------------------------------------------------- | +| `struct discord` | the client stucture | +| char[] | The chat command expected to trigger a callback response | +| `discord\_on\_message` | the message type function callback to run when its corresponding event is triggered | -### [discord\_run()](https://cee-studio.github.io/orca/apis/discord.html#c.discord_run) +### discord\_run() `discord_run(struct discord*)`: establishes a connection to Discord, run until error or shutdown -| Member Parameters | Description | -| :------------------------------------------------------------------------------ | :------------------ | -| [struct discord](https://cee-studio.github.io/orca/apis/discord.html#c.discord) | the client stucture | +| Member Parameters | Description | +| :-----------------| :------------------ | +| `struct discord` | the client stucture | ## Clean up the bot @@ -143,7 +143,7 @@ discord_run(client); discord_cleanup(client); ``` -### [discord\_cleanup()](https://cee-studio.github.io/orca/apis/discord.html?highlight=set_on_command#c.discord_cleanup) +### discord\_cleanup() `discord_cleanup(struct discord*)`: cleanup client initialized by `discord_init()` or `discord_config_init()`