add native module

If you need some functionality beyond what the fibjs native module provides, or if you want to contribute code to fibjs, then this article might be helpful to you.

write idl file

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

Before you start writing your own fibjs modules you need to write the 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 judges whether the lyrics are correct, and the return value is 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.jscommand , which will read and parse all the idl files in the idl directory, and generate the corresponding header files and documents. The generated header files will be stored in the "fibjs/include/ifs/" directory. For example, name.idl will automatically generate the header file ${{fibjs_project_dir}}/fibjs/include/ifs/name.h, which defines the class name_base.

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 that 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 files in the ${{fibjs_project_dir}}/fibjs/src/ directory and the header files 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.0and later versions, we have stripped the fibjs module for better reuse, so you still need to add the following sentence to fibjs/program/src/fibjs.cppthe importModulefunction : IMPORT_MODULE(name);to install custom modules.

compile and test

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

Summarize

Learned how to add and modify fibjs native modules and objects. We can write all kinds 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.