cee-studio / orca

About

Orca is implemented in plain C, its symbols are organized to be easily matched to the documentation of the API being covered.

This is done in order to:

• Minimize the need to thoroughly document every Orca API.
• Reduce our user's cognitive burden of having to read both Orca API documentation and supported REST API documentation.
• The codebase becomes easier to navigate.

Orca's implementation has minimum external dependencies to make bot deployment deadly simple.

Design

• Easy to reason about the code: the most native data structures, the simplest algorithms, and intuitive interfaces.

• Easy to debug (networking and logic) errors: extensive assertion and logging facilities.

• Easy to use for the end users: highly scalable, all transfers made with Orca are thread-safe.

Minimal example

#include <string.h> // strcmp()
#include <orca/discord.h>

void on_ready(struct discord *client) 
{
  const struct discord_user *bot = discord_get_self(client);
  log_info("Logged in as %s!", bot->username);
}

void on_message(struct discord *client, const struct discord_message *msg)
{
  if (strcmp(msg->content, "ping") != 0)
    return; // ignore messages that aren't 'ping'

  discord_async_next(client, NULL); // make next request non-blocking (OPTIONAL)
  struct discord_create_message_params params = { .content = "pong" };
  discord_create_message(client, msg->channel_id, &params, NULL);
}

int main(void)
{
  struct discord *client = discord_init(BOT_TOKEN);
  discord_set_on_ready(client, &on_ready);
  discord_set_on_message_create(client, &on_message);
  discord_run(client);
}

This is a minimalistic example, refer to examples/ for a better overview.

Build Instructions

On Windows

• Install WSL2 and get either Ubuntu or Debian here.
• Make sure you are in your Linux $HOME folder before proceeding!
• Continue to On Linux and follow your distro's building steps.

On Linux

The only dependency is curl-7.4.1 or higher

Ubuntu and Debian

$ sudo apt install -y build-essential libcurl4-openssl-dev

Void Linux

$ sudo xbps-install -S libcurl-devel

Setting up your environment

Clone orca into your workspace

$ git clone https://github.com/cee-studio/orca.git && cd orca

Compile orca

$ make

Configuring orca

The following outlines the default fields of config.json

{
  "logging": { // logging directives
    "level": "trace",        // trace, debug, info, warn, error, fatal
    "filename": "bot.log",   // the output file
    "quiet": false,          // change to true to disable logs in console
    "overwrite": false,      // overwrite existing file with "filename"
    "use_color": true,       // log with color
    "http": {
      "enable": true,        // generate http specific logging
      "filename": "http.log" // the output file
    },
    "disable_modules": ["WEBSOCKETS", "USER_AGENT"] // disable logging for these modules
  },
  ...         // API directives (discord, slack, github, etc)
}

Test Echo-Bot

1. Get your bot token and add it to config.json, by assigning it to discord's "token" field. There are well written instructions from the discord-irc about how to get your bot token and adding it to a server.
2. Build example executables:

   $ make examples

3. Run Echo-Bot:

   $ cd examples && ./bot-echo

Get Echo-Bot Response

Type a message in any channel the bot is part of and the bot should send an echo response in return.

Terminate Echo-Bot

With Ctrl+c or by closing the Terminal.

Create your first bot

• Head to my_bot/, a special folder set-up for your convenience that may be modified freely.
• Read our guide for building your first bot.

Installing orca

Orca can be installed in case developing inside of my_bot/ doesn't suit your needs:

$ sudo make install

Included headers must be orca/ prefixed:

#include <orca/discord.h>

Standalone executable

GCC (Recommended)

$ gcc myBot.c -o myBot -pthread -ldiscord -lcurl

Clang

$ clang myBot.c -o myBot -pthread -ldiscord -lcurl

Recommended debuggers

First, make sure your executable is compiled with the -g flag to ensure human-readable debugger messages.

Valgrind

Using valgrind to check for memory leaks:

$ valgrind --leak-check=full ./myBot

For a more comprehensive guide check Valgrind's Quick Start.

GDB

Using GDB to check for runtime errors, such as segmentation faults:

$ gdb ./myBot

And then execute your bot from the gdb environment:

(gdb) run

If the program has crashed, get a backtrace of the function calls leading to it:

(gdb) bt

For a more comprehensive guide check Beej's Quick Guide to GDB

Support

Problems? Check out our Discord Server.

Links

• Documentation
• Building your first bot
• Contributing

Contributing

Check our Contributing Guidelines to get started! If you are here for the Discord API, please check our Discord API Roadmap.

Give us a star if you like this project!