Add native module

If you need some features other than those provided by the fibjs native module, or you want to contribute code to fibjs, then this article may be helpful to you.

Write idl file

idl is a descriptive language used to define native modules and object methods in fibjs.

Before you start writing your own fibjs module, you need to write idl descriptive language. Let's take the custom module name as an example. I need to write the descriptive language name.idl and put this file in the ${{fibjs_project_dir}}/idl/zh-cn/ directory, where ${{fibjs_project_dir}} represents the directory where the fibjs project is located.

Our name module is very simple. There is only one test method. Its parameter is a string. This string is the lyrics. The test method determines whether the lyrics are correct, and the return value is a boolean type. name.idl is written as follows

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/*! @brief name module

 how to use
 @code
 var name = require('name');
 @endcode
 */
module name
{
    /*! @brief 测试输入的字符串是不是正确的歌词
     @param lyrics 歌词
    */
    static Boolean test(String lyrics);
};

Generate header file

Execute the fibjs idlc.js command in the tools directory. This will read all idl files in the idl directory and parse them to generate corresponding header files and documents. The generated header files will be stored in the "fibjs/include/ifs/" directory under. For example, name.idl will automatically generate the header file ${{fibjs_project_dir}}/fibjs/include/ifs/name.h, which defines the name_base class.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
/***************************************************************************
 *                                                                         *
 *   This file was automatically generated using idlc.js                   *
 *   PLEASE DO NOT EDIT!!!!                                                *
 *                                                                         *
 ***************************************************************************/

#ifndef _name_base_H_
#define _name_base_H_

/**
 @author Leo Hoo <lion@9465.net>
 */

#include "../object.h"

namespace fibjs {

class name_base : public object_base {
    DECLARE_CLASS(name_base);

public:
    // name_base
    static result_t test(exlib::string lyrics, bool& retVal);

public:
    static void s__new(const v8::FunctionCallbackInfo<v8::Value>& args)
    {
        CONSTRUCT_INIT();

        Isolate* isolate = Isolate::current();

        isolate->m_isolate->ThrowException(
            isolate->NewString("not a constructor"));
    }

public:
    static void s_test(const v8::FunctionCallbackInfo<v8::Value>& args);
};
}

namespace fibjs {
inline ClassInfo& name_base::class_info()
{
    static ClassData::ClassMethod s_method[] = {
        { "test", s_test, true }
    };

    static ClassData s_cd = {
        "name", true, s__new, NULL,
        ARRAYSIZE(s_method), s_method, 0, NULL, 0, NULL, 0, NULL, NULL, NULL,
        &object_base::class_info()
    };

    static ClassInfo s_ci(s_cd);
    return s_ci;
}

inline void name_base::s_test(const v8::FunctionCallbackInfo<v8::Value>& args)
{
    bool vr;

    METHOD_NAME("name.test");
    METHOD_ENTER();

    METHOD_OVER(1, 1);

    ARG(exlib::string, 0);

    hr = test(v0, vr);

    METHOD_RETURN();
}
}

#endif

Write source code

The method s_test is a v8 accessor, which wraps the method test. Here we only need to implement the test method. The test method has two parameters, v0 is the input lyrics, and vr is the return value. We put the cpp file in the ${{fibjs_project_dir}}/fibjs/src/ directory, and the header file in the ${{fibjs_project_dir}}/fibjs/include directory. No additional header files are required for this example. We create a new file name.cpp in the fibjs/src/ directory with the following content:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
#include "object.h"
#include "ifs/name.h"

namespace fibjs
{
    DECLARE_MODULE(name);
    result_t name_base::test(exlib::string lyrics, bool& retVal)
    {
        if (lyrics == "youmeiyounameyishougehuirangnituranxiangqiwo")
            retVal = true;
        else retVal = false;

        return 0;
    }
}

It should be noted that DECLARE_MODULE(name); this sentence, this sentence declares the "name" module and registers it on the javascript object. This sentence needs to be added when writing the source code. In v0.25.0 and later versions, we stripped out the fibjs module for better reuse, so you still need to add the following sentence to the importModule function in the fibjs/program/src/fibjs.cpp file: IMPORT_MODULE(name); to install a custom module.

Compile and test

Before compiling on windows, you need to execute fibjs tools/vsmake.js and then build. The compilation and running results are as follows:

to sum up

Learned how to add and modify native modules and objects of fibjs. We can write a variety of complex modules, and we can also port third-party libraries to fibjs as support to write our modules. You are welcome to contribute more to fibjs.