Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC: QUICKSTART: KEIL #57

Merged
merged 4 commits into from
Jun 16, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions .github/workflows/keil-pack.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
name: "Build Keil pack"

on:
push:
paths:
- "src/**.c"
- "inc/**.h"
- ".github/workflows/keil-pack.yml"
pull_request:
branches: [master]
paths:
- "src/**.c"
- "inc/**.h"
- ".github/workflows/keil-pack.yml"
workflow_dispatch:
inputs:
logLevel:
description: "Log level"
required: true
default: "warning"

jobs:
pack-file:
runs-on: "ubuntu-latest"
steps:
- name: Checkout
uses: actions/checkout@v3
with:
submodules: true
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,7 @@ coverage: test
# 测试覆盖率, 并携带报告
coverage_report: coverage | $(COVERAGE_DIR)
@echo $(GCOV_REPORT_DISPLAY)
@$(COV_REPORT) --exclude "test_*" --exclude "thirds/*" --html --html-details --output "$(COVERAGE_DIR)/index.html"
@$(COV_REPORT) --source-encoding=utf-8 --exclude "test_*" --exclude "thirds/*" --html --html-details --output "$(COVERAGE_DIR)/index.html"
@echo $(GCOV_REPORT_DISPLAY) completed.

$(BUILD_DIR)/%.o: %.c Makefile | $(BUILD_DIR)
Expand Down
4 changes: 4 additions & 0 deletions www/.gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,7 @@ node_modules
!*.svelte
!*.scss
!*.svg
!*.webp
!*.gif
!*.png

1 change: 1 addition & 0 deletions www/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,7 @@
"@sveltejs/kit": "^1.5.0",
"@types/cookie": "^0.5.1",
"@types/markdown-it": "^12.2.3",
"@types/node": "^20.3.1",
"@typescript-eslint/eslint-plugin": "^5.59.6",
"@typescript-eslint/parser": "^5.59.6",
"eslint": "^8.40.0",
Expand Down
73 changes: 72 additions & 1 deletion www/src/texts/en/QUICKSTART.md
Original file line number Diff line number Diff line change
@@ -1 +1,72 @@
TODO Quick start
---
typora-root-url: ..\
---

This section shows how to add the `MtFmt` library to your project. In the latest version, we provide a CMake file in the repository. You can add the source files by hand or by git submodule.

[toc]

# Download

A simple way to download source files is that [click here](https://github.com/MtFmT-Lib/mtfmt/archive/refs/heads/master.zip). It will download the zip file from the main branch of the [GitHub repository](https://github.com/MtFmT-Lib/mtfmt). The other way is to install git and run the following command in your terminal, which is suitable for the professional developer.

```bash
git clone --depth=1 git@github.com:MtFmT-Lib/mtfmt.git
# or: https://github.com/MtFmT-Lib/mtfmt.git if you have not ssh key
```

You can add it to the git submodule also.

```bash
git submodule add git@github.com:MtFmT-Lib/mtfmt.git
```

# Add into project

The two folders should be included in the archive file. The `src` folder including C source files is all implementations. And, the `inc` folder includes C header files and C++ wrapper header files. A reasonable approach is to create a new folder to contain the `inc` and the `src` directories and copy that into your project directory.

## The Keil IDE

Using the middleware package is an easy way to add to the Keil IDE. You can find them here. As an alternative option, you can add the sources and configure the including path manually.

### Using the package

The middleware package was auto-generated by GitHub action.

TODO

### Add sources by Manual

Firstly, select the "Add existing file to Source Group" option like the figure 1.

![Figure 1. Add existing file menu item](./img/keil_add_ext_src_nlfs.png)

Then, add all files in the folder `src` into your project.

![Figure 2. Add existing file to source group](./img/keil_add_ext_src_step2_nlfs.png)

Now you add all source files succeeded. The next step is that add the including directory. The preprocessor must know where the file locates in that the preprocessor of the C compiler will copy the header into the source file simply. To add that to the project, click the "Options for Target" button in the toolbar.

![Figure 3. The "Options for Target" button](./img/keil_opt_for_target_btn.png)

Then find the "C/C++" tab and click the "..." button on the right side of the edit box.

![Figure 4. Including path in keil](./img/keil_cxx_opt_tab.png)

And select the `inc` folder in the dialog.

![Figure 5. Add an including path item](./img/keil_cxx_add_inc_path_step2.png)

Finally, we must set the C99 standard.

![Figure 6. Select C99 standard](./img/keil_c_standard.png)

Now you completed this section! Click the "Build" button or press the `F7` key to build your project and check the output has not any errors.

## The others

TODO

# Add it by CMake

The CMake file includes the archive also.
Binary file added www/src/texts/img/keil_add_ext_src_nlfs.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added www/src/texts/img/keil_add_ext_src_step2_nlfs.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added www/src/texts/img/keil_c_standard.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added www/src/texts/img/keil_cxx_opt_tab.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added www/src/texts/img/keil_opt_for_target_btn.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
19 changes: 19 additions & 0 deletions www/src/themes/webpages/markdown.scss
Original file line number Diff line number Diff line change
Expand Up @@ -17,9 +17,21 @@

// 段落文本
p {
margin: 0;
margin-top: 0.5em;
text-indent: 2em;
word-wrap: break-word;

img {
display: block;
margin: 0 auto;
padding-top: 0.8em;

// 宽高限制
max-width: 22em;
max-height: 17em;
}

code {
padding-left: 0.1em;
padding-right: 0.1em;
Expand Down Expand Up @@ -99,4 +111,11 @@
.toc-level1-content {
font-weight: 600;
}

.img-info {
font-size: 0.9em;
text-align: center;
margin-top: 0.4em;
margin-bottom: 1em;
}
}
75 changes: 73 additions & 2 deletions www/vite.config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@ import MarkdownIt from 'markdown-it'
import { textVide } from 'text-vide'
import { katex } from '@mdit/plugin-katex'
import Token from 'markdown-it/lib/token'
import * as fs from 'node:fs'
import path from 'node:path'

export default defineConfig({
plugins: [
Expand Down Expand Up @@ -42,6 +44,8 @@ function markdown_preprocess(): MarkdownIt {
})
// katex
markdown.use(katex)
// 嵌入图片
markdown.use(plugin_embed_image)
// 超链接的addr
markdown.use(plugin_section_id)
// 断行
Expand All @@ -51,6 +55,49 @@ function markdown_preprocess(): MarkdownIt {
return markdown
}

/**
* 嵌入图片
*/
function plugin_embed_image(md: MarkdownIt): void {
md.core.ruler.push('embed-image', state => {
state.tokens.forEach(token => {
if (token.type === 'inline') {
if (token.children === null) {
return
}
if (token.children.length !== 1) {
return
}
if (token.children[0].type !== 'image') {
return
}
// 图片转换为base64
const img_child = token.children[0]
const img_path = img_child.attrGet('src')
if (img_path !== null) {
const img_base64 = readfile_as_base64(img_path)
img_child.attrSet('src', img_base64)
}
// 添加图注
// 总而言之它以一种很奇怪的方式跑了起来...
const img_alt = img_child.attrGet('alt') ?? ''
let img_alt_content: string
if (img_alt.length > 0) {
img_alt_content = img_alt
}
else {
img_alt_content = img_child.content
}
const text_token = make_html_token(img_alt_content)
token.children.push(make_html_token('<div class="img-info">'))
token.children.push(text_token)
token.children.push(make_html_token('</div>'))
}
})
})
md.enable(['embed-image'])
}

/**
* 段落id
*/
Expand Down Expand Up @@ -235,6 +282,32 @@ function highlight_process(str: string, lang: string): string {
}
}

/**
* 读取文件并转为base64
*/
function readfile_as_base64(file: string): string {
const src_path = path.resolve('./src/texts')
const full_path = path.resolve(src_path, file)
const file_ext_name = path.extname(full_path)
// 读取并转换base64
const fs_data = fs.readFileSync(full_path)
const base64 = fs_data.toString('base64')
// 转换mime type
const mime_lut = new Map([
['.gif', 'image/gif'],
['.png', 'image/png'],
['.jpg', 'image/jpeg'],
['.jpeg', 'image/jpeg'],
['.webp', 'image/webp'],
])
const mime_type = mime_lut.get(file_ext_name)
if (mime_type) {
return 'data:' + mime_type + ';base64,' + base64
} else {
throw `No mime type for extname ${file_ext_name}`
}
}

/**
* 构造text的标签
*/
Expand All @@ -250,8 +323,6 @@ function make_text_token(str: string): Token {
token.markup = ''
token.info = ''
token.meta = null
token.block = false
token.hidden = false
return token
}

Expand Down