3.1. 十分钟部署到新平台

3.1.1. 如何选择可以运行 pikascript 的平台

  • PikaScript 可以在所有 支持 libc裸机操作系统上运行。

  • 编译器需要能够支持 C99 标准

  • 支持 32位/64位 内核,不支持 8 位内核。

  • 资源占用

    • 如果是 arm 内核,考虑到拓展模块的资源占用,最低应该配备 64k flash8k ram

    • 如果是 risc-v 内核,则需要 128k flash8k ram , 因为 risc-v 内核的 gcc 优化以及代码密度等问题,代码体积比 arm 内核大很多。

    • 如果是 其他内核,可以参考 risc-v 的配置需求。

  • 如果是 PC /服务器平台,则 linux/windows 均可。

在本篇文档中,将会介绍为新平台部署 PikaScript 的方法。PikaScript 几乎没有全局变量和宏仅依赖标准库,因此为新平台部署 PikaScript 是非常容易的。

下面是部署 PikaScript 的具体步骤

3.1.2. 准备模板工程

你的模板工程仅需要包含一个支持 printf 串口初始化,然后就可以愉快地使用 pikascript 了。 通常的脚本解释器都依赖操作系统文件系统,而 pikascript 不需要这些,如果你部署过其他的脚本引擎,就会发现 PikaScrip 具有真正的超轻量级特性。

3.1.3. 获取 PikaScript 源码和工具集

获取 PikaScsript 可以使用 pika 包管理器(方案1),或者使用官网的工程生成器(方案2)。

方案2是方案1的自动化版本,推荐新手第一次部署时使用方案1,以熟悉包管理器。

3.1.3.1. 方案1 使用 pika 包管理器

3.1.3.1.1. 下载 PikaScript 包管理器

PikaScript 包管理器可以帮助你拉取 pikascript 所需要的所有源码工具,并且提供版本选择功能,方便你切换版本。并且 PikaScript 包管理器使用 gitee 源,能够在大陆顺畅地使用,不需要科学上网。

进入 PikaScript 主仓库

https://github.com/mimilib/pikascript

或者:

https://gitee.com/lyon1998/pikascript

下载 PikaScript 包管理器 PikaPackage.exe

_images/1638721231166-cca4d1c4-d8a7-4cfd-be3c-fee9a548c10d-164649951515223.png

然后打开你要部署的工程,在工程的根目录下新建 pikascript 文件夹,然后把 PikaPackage.exe 复制进去。

_images/142019778-c727336c-9b6a-4a82-b813-1671f4120152.png

3.1.3.1.2. 安装模块

接下来,在 PikaPackage.exe 的帮助下我们可以轻松地拉取指定版本的源码和模块。拉取源码和模块通过一个requestment.txt 的文件,如果你熟悉 python 的 pip 包管理器,就会发现,pikascript 的 requestment.txt 文件格式与 pip 是一致的。

在项目的 pikascript 文件夹下新建一个 requestment.txt 文件,然后写入以下内容。

  1. pikascript-core==v1.11.0
  2. PikaStdLib==v1.11.0

requestment.txt 文件中表示表示使用 v1.10.0 版本的 pikascript 解释器内核和 v1.10.0 版本的标准库,解释器内核和标准库是必选项,这两个的版本号保持一致即可,而其他的模块可以有选择地添加,在初次部署时,应当只添加内核和标准库以避免遇到兼容性问题。

目前只支持 == 符号,表示严格匹配版本号。

还有一个特殊的版本是 latest,表示拉取最新的模块,这个最新指的是 pikascript 仓库中 master 分支的最新版本。如果你是模块的使用者而非开发者,请注意不要使用 latest 版本。因为 latest 版本在不断变动,新版本的模块可能导致兼容性问题。

你可以照抄 stm32g070 的 requestment.txt 内核和标准库版本, 这是官方支持的开发板 Pika派—Zero 所使用的版本。而所有可选的版本可以在 packages.toml 文件中查看。

现在的 pikascript 文件夹就有了 pikaPackage.exe 和 requestment.txt 两个文件,双击运行 pikaPackage.exe,在 requestmemt.txt 中指定的源码和模块就会被拉取下来。

_images/142022949-54585060-8612-42a8-a585-8c3e514a8be3.png

拉取后的文件如下图所示,pikascript-core 是内核源码,pikascript-lib 是模块库,pikascript-api 是模块 API , rust-msc-latest-win10.exe 是 pikascript 专用的预编译器。

_images/142023882-51ee4013-8318-483e-8ea4-5c57a5ffb6c6.png

如果你想升级版本,在 requestment.txt 中修改版本号然后再次运行 pikaPackage.exe 即可,原先的版本会被覆盖。

3.1.3.1.3. 编写 main.py

拉取完源码之后,接下来编写 pikascript 运行的 python 脚本,我们在 pikascript 文件夹新建一个 main.py 文件。

然后写入:

  1. import PikaStdLib
  2. print('hello PikaScript!')

其中import PikaStdLib 表示导入标准库,标准库是必须要导入的,即使没有直接用到,而print('hello PikaScript!')用于测试pikascript是否正常启动。

3.1.3.2. 方案2 使用官网的工程生成器

进入官网:http://pikascript.com/

_images/1644385174348-05a3dcee-5132-4c57-9716-dffa252540bf.png

平台选择 template, 然后点击 “开始生成” 即可获取默认的 reqeustment.txt,main.py,和 pikaPackages.exe,在生成工程的同时,源码和工具就已经自动打包好了。

3.1.4. 预编译模块

接下来运行 rust-msc-latest-win10.exe,将 main.py 和导入的模块预编译为 pikascript 的 api 文件,预编译后的文件在 pikascript-api 文件夹内。 _images/1644385072048-6354164c-e040-4318-a947-0114125e2d1d.png 我们打开 pikascript-api 文件夹,发现里面有一些 .c 和 .h 文件,就说明预编译是成功的,pikascript 预编译器可以把 python 模块预编译为 .c 和 .h 文件。 _images/1644385073271-a39b8d40-f722-4a0c-9b50-e7357f0eae48.png

3.1.5. 添加源码

在 Project 中新建三个 group ,建议命名为 pikascript-core, pikascript-api 和 pikascript-lib

_images/130967351-597b8f6b-cc4e-4bc3-9cb6-2f335e5dccea.png

然后将 pikascript 文件夹内的三个子文件夹下的 .c 文件(包括 pikascript-lib 里的子文件夹)全部添加到 keil 工程里(实际的 .c 文件个数可能和截图不一致,全部添加即可。)

_images/130971776-41d8c940-42d0-407d-872e-53525ce299a6.png

再然后为 pikascript-core 和 pikascript-api 文件夹添加 include 路径

_images/130967813-94016b8a-e408-4b49-b1e1-76a5df5fe984.png

_images/130967949-8399c65b-5584-4674-a947-e40103d953ea.png

3.1.6. 调整堆栈

打开工程的启动文件, 在 stm32 中, 这是一个 startup_stm32xxxx.s 的文件,而在其他平台上,你要自己弄清楚如何调整堆栈。

_images/130966276-24014a0a-90a6-4bd7-96b7-fde54806b8c3.png

建议分配 4K 的栈空间和 16K 的堆空间,最少也需要分配 1K 的栈空间和 4K 的堆空间

4K 栈空间对应 0x1000, 16K 堆空间对应 0x4000,如下图所示

_images/130967178-a985a4f5-730c-47fd-9317-68f33bc00066.png

3.1.7. 启动 PikaScript

在 main.c 的初始化代码中添加 PikaScript 的启动代码。

  • 添加头文件

在头文件中加入

  1. #include "pikascript.h"

_images/130969048-4def9902-5f36-4798-9eac-ebbb1441087f.png

  • 初始化 pikaScript 并得到 pikascript 主对象的指针 pikaMain

在 main 函数中加入一句启动代码

  1. PikaObj* pikaMain = pikaScriptInit();

_images/130969274-ff2fdf6f-2389-466b-b51e-e7bc33472558.png

结束了?对,结束了,就这么简单,是不是很神奇。

这是因为预编译器在背后做了很多辅助工作,包括自动生成pikaScriptInit()函数。

3.1.8. 编译源码

编译源码时需要勾选 C99 标准,而编译优化等级可以任意选择,pikascript 均支持。

_images/130968626-7d8d4f46-eb0c-4ccd-9c34-eab160b290f5.png

然后直接编译即可,一般来说是可以直接通过的,使用 compiler version 5 或者 compiler version 6 均可。

3.1.9. 贡献 BSP

我们真诚地感谢您的贡献,通过贡献代码,您可以帮助 PikaScript 运行在更多的平台上,更多的开发者将因您而受益。

操作方法参考 参与贡献 -> 贡献 BSP 章节

3.1.10. 添加外设支持

PikaScript 通过 package 管理外设,为平台添加外设支持请参考 标准库 -> StdDevice 标准设备C 模块 章节。