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, the parameter is a string, this string is the lyrics, the test method judges 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

Executed in the tools directory fibjs idlc.jscommand, which reads all the files in the idl idl directory and parse, generate the corresponding header files and documentation, which generated header files are 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 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;
    }
}

Note that DECLARE_MODULE(name);this sentence, the sentence declares the "name" of this module and register it to the javascript object. This sentence needs to be added when writing the source code. In v0.25.0future versions and we will fibjs modules stripped out in order to better reuse, so you still need to fibjs/program/src/fibjs.cppfile importModule, add the following sentence function: IMPORT_MODULE(name);to install a custom module.

Compile and test

Before compiling on windows, you need to run it again fibjs tools/vsmake.jsand then build. The compile and run results are as follows:

Summarize

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