9.4. How to contribute to the standard library

    Some of these libraries provide APIs consistent with or similar to CPython, and some provide common tools for MCU development.

    The PikaScript standard library is cross-platform, so it can’t use the proprietary resources of the platform (e.g. stm32), to ensure this, the standard library is developed on linux platform.

    PikaScript deploys GoogleTest unit testing framework on linux platform to provide test cases for these standard libraries, GoogleTest can be run on the developer’s local machine and also automatically in the cloud (based on Github Actions).

    VSCODE provides tools to connect to containers for development, and the development experience is as good as if you were outside the container.

    Select Remote, Containers, pikadev in the VSCODE sidebar, then click Open Directory to connect to Docker inside VSCODE.

    The first time you open it, you need to wait for some plugins to be installed automatically, then you can open it again and start it directly.

    _images/image-20220601001641800.png

    cd to ~/pikascript/port/linux, then type to switch the working path to pikascript/port/linux

    The pyi declaration files for the standard library are in the package/pikascript directory. The standard library includes PikaStdLib.pyi, PikaStdData.pyi, PikaDebug.pyi, PikaStdTask.pyi, etc.

    The implementation files are in the PikaStdLib folder.

    _images/image-20220601002350438.png

    Then you can add classes, or functions to the standard library, for example, add a startswith() method to the PikaStdData.String class by first adding a declaration for the startswith() method under the String class in PikaStdData.pyi.

    Then run.

    Then open PikaStdData_String.h and you will find the c function declaration for the automatically generated startswith method.

    _images/image-20220601003545995.png

    Next, implement this function in PikaStdData_String.c.

    Then you can run GoogleTest to see if it breaks the original code.

    1. sh gtest.sh

    _images/image-20220601003830732.png

    If the tests all pass, you can write the code for the functional tests.

    The test code is in the test directory.

    The tests for the standard library can be placed under pikaMain-test.cpp.

    The contents of a test case are as follows: first, declare a test case with the TEST macro, then fill in the name of the test group, and the name of the test case, the name of the test group can be the same as the other test cases in the current file, the test name needs to be different from the other test cases.

    1. TEST(<test group>, <test name>){
    3.     /* do something */
    5.     /* assert */
    6.     /* deinit */

    The measurement example is divided into three main parts.

    • Running

    • Judgment

    • Analysis

      Here is a typical test case, we copy this test case and change the name of the test case.

    We modify the obj_run() part, run a python script, and then take the result and use the EXPECT_EQ macro to determine the result.

    1. TEST(pikaMain, string_startswith) {
    2.     /* init */
    3.     pikaMemInfo.heapUsedMax = 0;
    4.     PikaObj* pikaMain = newRootObj("pikaMain", New_PikaMain);
    5.     /* run */
    6.     obj_run(pikaMain, 
    7.     "a = PikaStdData.String('test')\n"
    8.     "res1 = a.starswith('te')\n"
    9.     "res2 = a.startswith('st')\n"
    10.     /* collect */
    11.     int res1 = obj_getInt(pikaMain, "res1");
    14.     /* assert */
    15.     EXPECT_EQ(res1, 1);
    16.     EXPECT_EQ(res2, 0);
    18.     /* deinit */
    19.     obj_deinit(pikaMain);
    20.     EXPECT_EQ(pikaMemNow(), 0);
    21. }

    Then we run GoogleTest again

    1. sh gtest.sh

    As you can see, the number of test cases is 331, one more than the previous 330, and they all pass, which means the test is successful.

    _images/image-20220601005050927.png

    Once the test passes, you can commit the changes.

    Before committing the changes, you need to fork the PikaScript repository, Gitee and Github are both available.

    The first time you commit, you need to change your commit information, including your username, email, and the repository address after fork.

    Run

    1. sh push-core.sh

    Commit the modified code to ~/pikascript/package/PikaStdLib.

    Then run

      Enter the commit information, and if you are not familiar with vim, learn the basics of using vim yourself.

      Next you can commit

      If there is a conflict, you can first

      and then git push. For more information on how to use git, see the git manual.

      _images/image-20220601005949285.png

      Then launch a Pull Request in gitee / github