Skip to content

Commit e07e8c4

Browse files
realybinrealybin
committed
feat(i18n): add English documentation
1 parent 8a78751 commit e07e8c4

File tree

21 files changed

+414
-35
lines changed

21 files changed

+414
-35
lines changed

‎docfx.json

Lines changed: 21 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -6,17 +6,31 @@
66
"files": [
77
"**/*.{md,yml}"
88
],
9-
"exclude": [
10-
"_site/**"
11-
]
9+
"src": "docs/",
10+
"dest": "./"
1211
}
1312
],
1413
"resource": [
1514
{
1615
"files": [
1716
"images/**"
18-
]
17+
],
18+
"dest": "./"
19+
},
20+
{
21+
"files": [
22+
"docs/_images/**"
23+
],
24+
"dest": "./"
25+
},
26+
27+
{
28+
"files": [
29+
"index.html"
30+
],
31+
"dest": "./"
1932
}
33+
2034
],
2135
"output": "_site",
2236
"template": [
@@ -25,10 +39,9 @@
2539
"templates/material"
2640
],
2741
"fileMetadata": {
28-
"_appTitle":
29-
{
30-
"docs/avalonia/**/*.md": "OpenHarmony.Avalonia",
31-
"docs/blazor-hybrid/**/*.md": "OpenHarmony.BlazorHybrid"
42+
"_appTitle": {
43+
"docs/*/avalonia/**/*.md": "OpenHarmony.Avalonia",
44+
"docs/*/blazor-hybrid/**/*.md": "OpenHarmony.BlazorHybrid"
3245
}
3346
},
3447
"globalMetadata": {

‎images/Header.png renamed to ‎docs/_images/Header.png

File renamed without changes.

‎docs/en-us/articles/avalonia/index.md

Whitespace-only changes.

‎docs/en-us/articles/avalonia/introduction.md

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# Introduction
2+
3+
> [!CAUTION]
4+
> Before the project is ready for production, it may contain unstable APIs and features, including breaking changes. Please use with caution.
5+
6+
## Environment Setup
7+
8+
> [!NOTE]
9+
> The following methods apply to Windows. We have not yet tested this workflow on Linux/macOS.
10+
11+
* [Zig](https://ziglang.org/) provides `linker/sysroot` support for [OpenHarmony-NET.PublishAotCross](https://github.com/OpenHarmony-NET/PublishAotCross?tab=readme-ov-file#openharmony-netpublishaotcross) to allow cross-compilation for `linux-x64/linux-arm64/linux-musl-x64/linux-musl-arm64` targets on Windows
12+
13+
```shell
14+
# Install Zig on Windows via winget
15+
winget install zig.zig
16+
```
17+
18+
* [LLVM](https://releases.llvm.org/download.html) is needed for the compilation process that uses `llvm-objcopy.exe`, ensure it exists in your environment variables
19+
20+
* .NET 8.0 SDK and .NET 9.0 SDK
21+
22+
* Latest version of DevEco Studio
23+
24+
* _Optional_ `Visual Studio 2022`
25+
26+
* _Optional_ `JetBrains Rider`
27+
28+
## Build and Run
29+
30+
* Pull the latest code from [OpenHarmony.Avalonia](https://github.com/OpenHarmony-NET/OpenHarmony.Avalonia)
31+
32+
```shell
33+
git clone https://github.com/OpenHarmony-NET/OpenHarmony.Avalonia.git --recursive
34+
```
35+
36+
* Enter the project directory `OpenHarmony.Avalonia`
37+
38+
```shell
39+
|-- Directory.Build.props
40+
|-- OHOS_Project
41+
|-- OpenHarmony.Avalonia.sln
42+
|-- README.md
43+
|-- Src
44+
|-- ThirdParty
45+
46+
3 directories, 3 files
47+
```
48+
49+
Then execute the following command or use `Visual Studio 2022` to open the `OpenHarmony.Avalonia.sln` solution, right-click on the `Entry` project and publish
50+
51+
> [!NOTE]
52+
> `arm64-v8a` is suitable for physical devices, while `x86_64` is for emulators. Please choose according to your device type.
53+
54+
### [Physical Device](#tab/physical)
55+
56+
```shell
57+
dotnet publish ./Src/Entry/Entry.csproj -c Release -r linux-musl-arm64 -p:PublishAot=true -o OHOS_Project/entry/libs/arm64-v8a
58+
```
59+
60+
Or select `PublishArm64.pubxml` in the publish page, then click the publish button
61+
62+
### [Emulator](#tab/virtual)
63+
64+
```shell
65+
dotnet publish ./Src/Entry/Entry.csproj -c Release -r linux-musl-x64 -p:PublishAot=true -o OHOS_Project/entry/libs/x86_64
66+
```
67+
68+
Or select `PublishAmd64.pubxml` in the publish page, then click the publish button
69+
70+
---
71+
72+
* Open DevEco Studio, open the `OHOS_Project` directory, then click the run button. DevEco Studio will automatically install and run the application on your physical device/emulator
73+
74+
> [!NOTE]
75+
> Running on a physical device may require signing and other procedures, consistent with normal HarmonyOS software development
76+
77+
## Run Your Own Project
78+
79+
* Add your project reference to `Entry` (i.e., the Entry project references your project)
80+
81+
[And replace this namespace with your own software's namespace](https://github.com/OpenHarmony-NET/OpenHarmony.Avalonia/blob/2f0af9d19832c48a69e972eb263caf4a68f381c6/Src/Entry/XComponentEntry.cs#L5)
82+
83+
```diff
84+
using System.Runtime.CompilerServices;
85+
using System.Runtime.InteropServices;
86+
using Avalonia.OpenHarmony;
87+
using OpenHarmony.NDK.Bindings.Native;
88+
- using AOOH_Gallery;
89+
+ using YourProjectNamespace;
90+
91+
namespace Entry;
92+
```
93+
94+
[Also change the `App` class's project affiliation](https://github.com/OpenHarmony-NET/OpenHarmony.Avalonia/blob/2f0af9d19832c48a69e972eb263caf4a68f381c6/Src/Entry/XComponentEntry.cs#L21)
95+
96+
```diff
97+
try
98+
{
99+
Ace.OH_NativeXComponent_RegisterOnFrameCallback(component, &OnSurfaceRendered);
100+
if (XComponents.TryGetValue((nint)component, out var xComponent))
101+
return;
102+
+ xComponent = new AvaloniaXComponent<App>((nint)component, (nint)window);
103+
XComponents.Add((nint)component, xComponent);
104+
xComponent.OnSurfaceCreated();
105+
}
106+
```

‎docs/en-us/articles/blazor-hybrid/index.md

Whitespace-only changes.

‎docs/blazor-hybrid/introduction.md renamed to ‎docs/en-us/articles/blazor-hybrid/introduction.md

File renamed without changes.

‎docs/en-us/articles/index.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Getting Started
2+
3+
This article will introduce how to develop native libraries for the HarmonyOS system using .NET and NDK. If you want to develop complete HarmonyOS applications with .NET, please refer to the [Avalonia](avalonia/introduction.md) **and** Blazor Hybrid chapters.

‎docs/en-us/index.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
![OpenHarmony.NET](../_images/Header.png "Hello OpenHarmony.NET")
2+
3+
# Introduction
4+
5+
## 🤔What is OpenHarmony.NET?
6+
7+
OpenHarmony.NET is a solution designed specifically for **OpenHarmony** (including **HarmonyOS Next**), aimed at supporting **.NET** applications on the Harmony operating system. With OpenHarmony.NET, developers can use familiar **Avalonia** or **Blazor Hybrid** technologies to develop Harmony applications, and even use **C#** instead of **C++** for native library development. This provides .NET developers with a new platform, enabling them to easily introduce the .NET technology stack into the Harmony ecosystem.
8+
9+
## 😲Runtime Support
10+
11+
### · Adaptation Status
12+
OpenHarmony.NET has been successfully adapted to **.NET 9**, providing developers with a stable and efficient runtime environment.
13+
14+
### · Runtime Limitations
15+
1. **Only NativeAOT Available**:
16+
Due to Harmony system restrictions on runtime-generated assembly code (see [Harmony System Change Notes](https://developer.huawei.com/consumer/cn/doc/harmonyos-releases-V5/changelogs-for-all-apps-b031-V5#%E5%8C%BF%E5%90%8D%E5%86%85%E5%AD%98%E6%89%A7%E8%A1%8C%E6%9D%83%E9%99%90%E7%AE%A1%E6%8E%A7%E7%AD%96%E7%95%A5%E5%8F%98%E6%9B%B4%E8%AF%B4%E6%98%8E)), JIT (Just-In-Time) technology cannot be used. Therefore, OpenHarmony.NET adopts **NativeAOT (Native Ahead-Of-Time)** compilation. This method generates native machine code directly during compilation, ensuring efficient application execution on the Harmony system.
17+
18+
2. **Cannot Use `Marshal.GetDelegateForFunctionPointer` Related Functions**:
19+
For the same reason as above, direct use of function pointers is recommended.
20+
21+
## 🥰Framework Adaptation
22+
23+
### Supported Frameworks
24+
Currently, OpenHarmony.NET has successfully adapted the following two frameworks:
25+
1. **Avalonia**: A cross-platform UI framework that supports desktop application development using XAML and C#. For details, please refer to the [Avalonia Documentation](articles/avalonia/introduction.md).
26+
2. **Blazor Hybrid**: A hybrid development framework based on Blazor, allowing cross-platform application development using C# and Razor syntax. For details, please refer to the [Blazor Hybrid Documentation](articles/blazor-hybrid/introduction.md).
27+
28+
### More Framework Adaptations
29+
We welcome more .NET frameworks to join the OpenHarmony.NET ecosystem. If you are interested in adapting other frameworks, we are willing to share valuable experience accumulated during the adaptation of Avalonia and Blazor Hybrid to help you get started quickly.
30+

‎docs/en-us/toc.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
- name: Introduction
2+
href: index.md
3+
- name: Getting Started
4+
href: articles/index.md
5+
6+
- name: Framework
7+
- name: Avalonia
8+
href: articles/avalonia/introduction.md
9+
- name: Blazor Hybrid
10+
href: articles/blazor-hybrid/introduction.md

‎docs/toc.yml

Lines changed: 0 additions & 10 deletions
This file was deleted.

0 commit comments

Comments
 (0)