How To Start

Yuzhang Hu edited this page Jul 8, 2018 · 12 revisions

Install Skull

As mentioned in Introduction, Skull includes 3 majors parts: Engine, API and CLI. To play with it, install Skull first, then use skull commands to create/manage a Skull project.

Install Dependencies

The example environment is Ubuntu14.04. (Tested on Ubuntu 12.04/14.04/16.04 and RHEL6.x, Raspberry OS)

sudo apt-get install valgrind expect libyaml-dev python-dev python-pip libprotobuf-dev protobuf-compiler libprotobuf-c0-dev protobuf-c-compiler;
sudo pip install PyYAML protobuf==2.6.1 pympler WebOb;

git clone
cd skull
git submodule update --init --recursive
make dep
sudo make install-dep

Build and Install

make -j4
sudo make install


  • To disable jemalloc, use make -j4 disable_jemalloc=true to build it
  • For some Linux Releases, we might need to use CFLAGS, CXXFLAGS, LDFLAGS to finish the build

More Options:

  • -DSK_DUMP_CORE: On some platforms if we want to manual dump the backtrace when assertion failed, we can compile Skull with this macro.

After that, Skull has installed into the system, type skull we would see:

final@ubuntu1404: ~>skull
Skull 0.9.6 - A fast to start, easy to maintain, high productive serving framework.
More information see

 \_ skull create
 \_ skull config
 \_ skull common
 \_ skull workflow
 \_ skull module
 \_ skull service
 \_ skull build
 \_ skull deploy
 \_ skull start
 \_ skull version
 \_ skull help

Now, Skull is ready, read the following to create a project :)

Basic flow

skull demo 1

To create a basic skull project, we only need few steps:

  • skull create project
  • skull workflow --add
  • skull module --add
  • skull service --add (optional)

Play With It

After we created above, by default the Skull project is a echo-back server, we can play with it by running:

  • skull build
  • skull deploy
  • skull start

skull demo 2


When we created a Skull project, the default project config is: $project/config/skull-config.yaml, we would tune some flags if needed. (Run skull config will dump the config content as well)

thread_num: 1
command_port: 7759
bio: 1
log_name: skull.log
log_level: debug

# Optional workflow item 'bind4': which IPv4 address we want to bind, by default is

# Optional service item 'max_qsize': control the max_queue_size, by default is 1024
# Optional workflow item 'timeout': transcation timeout, unit is millisecond, by default is 0 (no timeout)

languages: [cpp, py]

# Optional global item 'max_fds': means max open files, if there is no right
#  permission to set it successfully, the engine will use the default bash value
## max_fds: 65535

Counter Definition File

The counter definition file for the created project is at $project/config/metrics.yaml:

final@ubuntu1404: ~/skull_tests/test>cat config/metrics.yaml
    type: static
            desc: module request counter
            desc: module response counter

# every transaction have its own metrics
    type: dynamic
            desc: transaction request count
            desc: transaction response count

Define the counters into this file, then every time when we run skull build or skull common --metrics-gen, the corresponding counter source file will be generated.

Module/Service Config Items

Cpp Module Config

The Module Configuration file is at src/modules/$ModuleName/config/config.yaml:

> cat config.yaml
test_item: 123
test_rate: 1.0
test_name: module
test_bool: true

So, users can define their own config items there, and every time when we run skull build or skull common --config-gen, Skull would convert this raw config file to a Cpp source file, then the user can use it easier without do a manual conversion.

Python Module Config

The Module configuration file is at src/modules/$ModuleName/config.yaml, and the Python module support full functionality of YAML parsing, which means users can define a complex config if needed. And every time when we run skull build or skull common --config-gen, Skull will convert this raw config file to a Python YAML Object, then it will pass to module_init entry.

Cpp Service Config

The service configuration file is at src/services/$ServiceName/config/config.yaml, everything is the same as the Cpp Module configuration.

Notes: Currently Skull does not support Python service due to the performance issue.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.