add objc examples

docs/config.ts

@@ -107,6 +107,13 @@ function examplesGuide(): DefaultTheme.SidebarItem[] {
         { text: 'MFC Programs', link: 'cpp/mfc' },
         { text: 'Protobuf Programs', link: 'cpp/protobuf' },
       ]
+    },
+    {
+      text: 'ObjC/C++',
+      collapsed: false,
+      items: [
+        { text: 'iOS/MacOS Programs', link: 'objc/xcode' },
+      ]
     }
   ]
 }

docs/examples/cpp/mfc.md

@@ -0,0 +1,31 @@
+## MFC Static Library
+
+```lua
+target("test")
+    add_rules("win.sdk.mfc.static")
+    add_files("src/*.c")
+```
+
+## MFC Shared Library
+
+```lua
+target("test")
+    add_rules("win.sdk.mfc.shared")
+    add_files("src/*.c")
+```
+
+## MFC Application (Static)
+
+```lua
+target("test")
+    add_rules("win.sdk.mfc.static_app")
+    add_files("src/*.c")
+```
+
+## MFC Application (Shared)
+
+```lua
+target("test")
+    add_rules("win.sdk.mfc.shared_app")
+    add_files("src/*.c")
+```

docs/examples/cpp/protobuf.md

@@ -0,0 +1,48 @@
+## Using c library
+
+```lua
+add_requires("protobuf-c")
+
+target("console_c")
+     set_kind("binary")
+     add_packages("protobuf-c")
+     add_rules("protobuf.c")
+     add_files("src/*.c")
+     add_files("src/*.proto")
+```
+
+We can also set ``proto_public = true`` to export the proto's header search directory and make it available for other parent targets to inherit from.
+
+```lua
+    add_packages("protobuf-c", {public = true})
+    add_files("src/**.proto", {proto_public = true})
+```
+
+::: tip NOTE
+Since the headers generated by protobuf reference the headers of the protobuf-c package, we also need to mark the package headers as `{public = true}` to export it.
+:::
+
+## Using the C++ library
+
+```lua
+add_requires("protobuf-cpp")
+
+target("console_c++")
+     set_kind("binary")
+     set_languages("c++11")
+     add_packages("protobuf-cpp")
+     add_rules("protobuf.cpp")
+     add_files("src/*.cpp")
+     add_files("src/*.proto")
+```
+
+We can also set ``proto_public = true`` to export the proto's header search directory and make it available for other parent targets to inherit from.
+
+```lua
+    add_packages("protobuf-cpp", {public = true})
+    add_files("src/**.proto", {proto_public = true})
+```
+
+::: tip NOTE
+Since the headers generated by protobuf reference the headers of the protobuf-cpp package, we also need to mark the package headers as `{public = true}` to export it.
+:::

docs/examples/cpp/wdk.md

@@ -0,0 +1,149 @@
+Xmake will detect WDK automatically and we can also set the WDK directory manually.
+
+```bash
+$ xmake f --wdk="G:\Program Files\Windows Kits\10" -c
+$ xmake
+```
+
+If you want to known more information, you can see [#159](https://github.com/xmake-io/xmake/issues/159).
+
+And see [WDK examples](https://github.com/xmake-io/xmake/tree/master/tests/projects/windows/driver)
+
+## UMDF Driver Program
+
+```lua
+target("echo")
+    add_rules("wdk.driver", "wdk.env.umdf")
+    add_files("driver/*.c")
+    add_files("driver/*.inx")
+    add_includedirs("exe")
+
+target("app")
+    add_rules("wdk.binary", "wdk.env.umdf")
+    add_files("exe/*.cpp")
+```
+
+## KMDF Driver Program
+
+```lua
+target("nonpnp")
+    add_rules("wdk.driver", "wdk.env.kmdf")
+    add_values("wdk.tracewpp.flags", "-func:TraceEvents(LEVEL,FLAGS,MSG,...)", "-func:Hexdump((LEVEL,FLAGS,MSG,...))")
+    add_files("driver/*.c", {rule = "wdk.tracewpp"})
+    add_files("driver/*.rc")
+
+target("app")
+    add_rules("wdk.binary", "wdk.env.kmdf")
+    add_files("exe/*.c")
+    add_files("exe/*.inf")
+```
+
+## WDM Driver Program
+
+```lua
+target("kcs")
+    add_rules("wdk.driver", "wdk.env.wdm")
+    add_values("wdk.man.flags", "-prefix Kcs")
+    add_values("wdk.man.resource", "kcsCounters.rc")
+    add_values("wdk.man.header", "kcsCounters.h")
+    add_values("wdk.man.counter_header", "kcsCounters_counters.h")
+    add_files("*.c", "*.rc", "*.man")
+```
+
+```lua
+target("msdsm")
+    add_rules("wdk.driver", "wdk.env.wdm")
+    add_values("wdk.tracewpp.flags", "-func:TracePrint((LEVEL,FLAGS,MSG,...))")
+    add_files("*.c", {rule = "wdk.tracewpp"})
+    add_files("*.rc", "*.inf")
+    add_files("*.mof|msdsm.mof")
+    add_files("msdsm.mof", {values = {wdk_mof_header = "msdsmwmi.h"}})
+```
+
+## Package Driver
+
+We can run the following command to generate a .cab driver package.
+
+```bash
+$ xmake [p|package]
+$ xmake [p|package] -o outputdir
+```
+
+The output files like:
+
+```
+  - drivers
+    - sampledsm
+       - debug/x86/sampledsm.cab
+       - release/x64/sampledsm.cab
+       - debug/x86/sampledsm.cab
+       - release/x64/sampledsm.cab
+```
+
+## Driver Signing
+
+The driver signing is disabled when we compile driver in default case,
+but we can add `set_values("wdk.sign.mode")` to enable test/release sign.
+
+### TestSign
+
+We can use test certificate of xmake to do testsign, but please run `$xmake l utils.wdk.testcert` install as admin to install a test certificate first (only once)!
+
+```lua
+target("msdsm")
+    add_rules("wdk.driver", "wdk.env.wdm")
+    set_values("wdk.sign.mode", "test")
+```
+
+Or we set a valid certificate thumbprint to do it in local machine.
+
+```lua
+target("msdsm")
+    add_rules("wdk.driver", "wdk.env.wdm")
+    set_values("wdk.sign.mode", "test")
+    set_values("wdk.sign.thumbprint", "032122545DCAA6167B1ADBE5F7FDF07AE2234AAA")
+```
+
+We can also do testsign via setting store/company info.
+
+```lua
+target("msdsm")
+    add_rules("wdk.driver", "wdk.env.wdm")
+    set_values("wdk.sign.mode", "test")
+    set_values("wdk.sign.store", "PrivateCertStore")
+    set_values("wdk.sign.company", "tboox.org(test)")
+```
+
+### ReleaseSign
+
+We can set a certificate file for release signing.
+
+```lua
+target("msdsm")
+    add_rules("wdk.driver", "wdk.env.wdm")
+    set_values("wdk.sign.mode", "release")
+    set_values("wdk.sign.company", "xxxx")
+    set_values("wdk.sign.certfile", path.join(os.projectdir(), "xxxx.cer"))
+```
+
+## Support Low-version System
+
+We can set `wdk.env.winver` to generate a driver package that is compatible with a low version system.
+
+```lua
+set_values("wdk.env.winver", "win10")
+set_values("wdk.env.winver", "win10_rs3")
+set_values("wdk.env.winver", "win81")
+set_values("wdk.env.winver", "win8")
+set_values("wdk.env.winver", "win7")
+set_values("wdk.env.winver", "win7_sp1")
+set_values("wdk.env.winver", "win7_sp2")
+set_values("wdk.env.winver", "win7_sp3")
+```
+
+We can also set windows version for WDK driver program:
+
+```bash
+$ xmake f --wdk_winver=[win10_rs3|win8|win7|win7_sp1]
+$ xmake
+```

docs/examples/cpp/winsdk.md

@@ -0,0 +1,10 @@
+
+```lua
+target("usbview")
+    add_rules("win.sdk.application")
+
+    add_files("*.c", "*.rc")
+    add_files("xmlhelper.cpp", {rule = "win.sdk.dotnet"})
+```
+
+If you want to known more information, you can see [#173](https://github.com/xmake-io/xmake/issues/173).

docs/examples/objc/xcode.md

@@ -0,0 +1,196 @@
+
+## Application
+
+Generate *.app/*.ipa application and supports iOS/MacOS.
+
+```lua
+target("test")
+    add_rules("xcode.application")
+    add_files("src/*.m", "src/**.storyboard", "src/*.xcassets")
+    add_files("src/Info.plist")
+```
+
+::: tip NOTE
+After 2.5.7, you can directly add `*.metal` files, xmake will automatically generate default.metallib for the application to load and use.
+:::
+
+### Create Project
+
+We can also quickly create project through template:
+
+```bash
+$ xmake create -t xcode.macapp -l objc test
+$ xmake create -t xcode.iosapp -l objc test
+```
+
+### Build Program
+
+```bash
+$ xmake f -p [iphoneos|macosx]
+$ xmake
+[ 18%]: compiling.xcode.release src/Assets.xcassets
+[ 27%]: processing.xcode.release src/Info.plist
+[ 72%]: compiling.xcode.release src/Base.lproj/Main.storyboard
+[ 81%]: compiling.xcode.release src/Base.lproj/LaunchScreen.storyboard
+[ 45%]: cache compiling.release src/ViewController.m
+[ 63%]: cache compiling.release src/AppDelegate.m
+[ 54%]: cache compiling.release src/SceneDelegate.m
+[ 36%]: cache compiling.release src/main.m
+[ 90%]: linking.release test
+[100%]: generating.xcode.release test.app
+[100%]: build ok!
+```
+
+### Codesign
+
+For iOS programs, it will detect that the system first signs the app with available signatures. Of course, we can also manually specify other signature certificates:
+
+```bash
+$ xmake f -p iphoneos --xcode_codesign_identity='Apple Development: [email protected] (T3NA4MRVPU)' --xcode_mobile_provision='iOS Team Provisioning Profile: org.tboox.test --xcode_bundle_identifier=org.tboox.test'
+$ xmake
+```
+
+If it is cumbersome to configure the signature every time, you can set it to the `xmake global` global configuration, or you can set it separately for each target in xmake.lua:
+
+```lua
+target("test")
+    add_rules("xcode.application")
+    add_files("src/*.m", "src/**.storyboard", "src/*.xcassets")
+    add_files("src/Info.plist")
+    add_values("xcode.bundle_identifier", "org.tboox.test")
+    add_values("xcode.codesign_identity", "Apple Development: [email protected] (T3NA4MRVPU)")
+    add_values("xcode.mobile_provision", "iOS Team Provisioning Profile: org.tboox.test")
+```
+
+How do we know the signature configuration we need? One is to view it in xcode. In addition, xmake also provides some auxiliary tools to dump all currently available signature configurations:
+
+```bash
+$ xmake l private.tools.codesign.dump
+==================================== codesign identities ====================================
+{
+  "Apple Development: [email protected] (T3NA4MRVPU)" = "AF73C231A0C35335B72761BD3759694739D34EB1"
+}
+
+===================================== mobile provisions =====================================
+{
+  "iOS Team Provisioning Profile: org.tboox.test" = "<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AppIDName</key>
+	<string>XC org tboox test</string>
+	<key>ApplicationIdentifierPrefix</key>
+	<array>
+	<string>43AAQM58X3</string>
+...
+```
+
+We also provide other auxiliary tools to re-sign existing ipa / app programs, for example:
+
+```bash
+$ xmake l utils.ipa.resign test.ipa | test.app [codesign_identity] [mobile_provision] [bundle_identifier]
+```
+
+Among them, the following signature parameters are optional, if not set, then a valid signature will be detected by default:
+
+```bash
+$ xmake l utils.ipa.resign test.ipa
+$ xmake l utils.ipa.resign test.app "Apple Development: [email protected] (T3NA4MRVPU)"
+$ xmake l utils.ipa.resign test.ipa "Apple Development: [email protected] (T3NA4MRVPU)" iOS Team Provisioning Profile: org.tboox.test" org.tboox.test
+```
+
+### Run the application
+
+Currently only supports running macos program:
+
+```console
+$ xmake run
+```
+
+The effect is as follows:
+
+![](/assets/img/guide/macapp.png)
+
+### Package program
+
+If it is an iOS program, it will generate an ipa installation package, if it is macOS, it will generate a dmg package (dmg package generation is still under development for the time being).
+
+```bash
+$ xmake package
+output: build/iphoneos/release/arm64/test.ipa
+package ok!
+```
+
+We also provide auxiliary tools to package the specified app program:
+
+```bash
+$ xmake l utils.ipa.package test.app output.ipa [iconfile.png]
+```
+
+### Install
+
+If it is an iOS program, it will install ipa to the device, if it is macos, it will install the app to the `/Applications` directory.
+
+```bash
+$ xmake install
+```
+
+We also provide auxiliary tools to install the specified ipa/app program to the device:
+
+```bash
+$ xmake l utils.ipa.install test.app
+$ xmake l utils.ipa.install test.ipa
+```
+
+### Uninstall
+
+::: tip NOTE
+Currently only the macos program is supported
+:::
+
+```bash
+$ xmake uninstall
+```
+
+## Framework Program
+
+```lua
+target("test")
+    add_rules("xcode.framework")
+    add_files("src/*.m")
+    add_files("src/Info.plist")
+```
+
+We can also quickly create project through template:
+
+```bash
+$ xmake create -t xcode.framework -l objc test
+```
+
+In addition, xmake v2.3.9 and above, xmake also provides a complete iosapp/macapp empty project template with framework library usage, you can fully experience framework compilation, dependent use and integration into app applications.
+
+At the same time, if we turn on the emulator, xmake can support directly `xmake install` and `xmake run` to install the app to the emulator and load and run it.
+
+```bash
+$ xmake create -t xcode.iosapp_with_framework -l objc testapp
+$ cd testapp
+$ xmake f -p iphoneos -a x86_64
+$ xmake
+$ xmake install
+$ xmake run
+```
+
+## Bundle Program
+
+```lua
+target("test")
+    add_rules("xcode.bundle")
+    add_files("src/*.m")
+    add_files("src/Info.plist")
+```
+
+We can also quickly create project through template:
+
+```bash
+$ xmake create -t xcode.bundle -l objc test
+```

docs/zh/config.ts

@@ -144,6 +144,13 @@ function examplesGuide(): DefaultTheme.SidebarItem[] {
         { text: 'MFC 程序', link: 'cpp/mfc' },
         { text: 'Protobuf 程序', link: 'cpp/protobuf' },
       ]
+    },
+    {
+      text: 'ObjC/C++',
+      collapsed: false,
+      items: [
+        { text: 'iOS/MacOS 程序', link: 'objc/xcode' },
+      ]
     }
   ]
 }

docs/zh/examples/objc/xcode.md

@@ -0,0 +1,196 @@
+
+## App 应用程序 {#application}
+
+用于生成*.app/*.ipa应用程序，同时支持iOS/MacOS。
+
+```lua
+target("test")
+    add_rules("xcode.application")
+    add_files("src/*.m", "src/**.storyboard", "src/*.xcassets")
+    add_files("src/Info.plist")
+```
+
+::: tip 注意
+2.5.7 之后，可以支持直接添加 `*.metal` 文件，xmake 会自动生成 default.metallib 提供给应用程序加载使用。
+:::
+
+### 创建工程 {#create-project}
+
+我们也可以通过模板工程快速创建：
+
+```bash
+$ xmake create -t xcode.macapp -l objc test
+$ xmake create -t xcode.iosapp -l objc test
+```
+
+### 编译 {#build}
+
+```bash
+$ xmake f -p [iphoneos|macosx]
+$ xmake
+[ 18%]: compiling.xcode.release src/Assets.xcassets
+[ 27%]: processing.xcode.release src/Info.plist
+[ 72%]: compiling.xcode.release src/Base.lproj/Main.storyboard
+[ 81%]: compiling.xcode.release src/Base.lproj/LaunchScreen.storyboard
+[ 45%]: cache compiling.release src/ViewController.m
+[ 63%]: cache compiling.release src/AppDelegate.m
+[ 54%]: cache compiling.release src/SceneDelegate.m
+[ 36%]: cache compiling.release src/main.m
+[ 90%]: linking.release test
+[100%]: generating.xcode.release test.app
+[100%]: build ok!
+```
+
+### 配置签名 {#configure-sign}
+
+对于iOS程序，默认会检测系统先用可用签名来签名app，当然我们也可以手动指定其他签名证书：
+
+```bash
+$ xmake f -p iphoneos --xcode_codesign_identity='Apple Development: [email protected] (T3NA4MRVPU)' --xcode_mobile_provision='iOS Team Provisioning Profile: org.tboox.test --xcode_bundle_identifier=org.tboox.test'
+$ xmake
+```
+
+如果每次这么配置签名觉得繁琐的话，可以设置到`xmake global`全局配置中，也可以在xmake.lua中对每个target单独设置：
+
+```lua
+target("test")
+    add_rules("xcode.application")
+    add_files("src/*.m", "src/**.storyboard", "src/*.xcassets")
+    add_files("src/Info.plist")
+    add_values("xcode.bundle_identifier", "org.tboox.test")
+    add_values("xcode.codesign_identity", "Apple Development: [email protected] (T3NA4MRVPU)")
+    add_values("xcode.mobile_provision", "iOS Team Provisioning Profile: org.tboox.test")
+```
+
+那如何知道我们需要的签名配置呢？一种就是在xcode里面查看，另外xmake也提供了一些辅助工具可以dump出当前可用的所有签名配置：
+
+```bash
+$ xmake l private.tools.codesign.dump
+==================================== codesign identities ====================================
+{
+  "Apple Development: [email protected] (T3NA4MRVPU)" = "AF73C231A0C35335B72761BD3759694739D34EB1"
+}
+
+===================================== mobile provisions =====================================
+{
+  "iOS Team Provisioning Profile: org.tboox.test" = "<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+	<key>AppIDName</key>
+	<string>XC org tboox test5</string>
+	<key>ApplicationIdentifierPrefix</key>
+	<array>
+	<string>43AAQM58X3</string>
+...
+```
+
+我们也提供了其他辅助工具来对已有的ipa/app程序进行重签名，例如：
+
+```bash
+$ xmake l utils.ipa.resign test.ipa|test.app [codesign_identity] [mobile_provision] [bundle_identifier]
+```
+
+其中，后面的签名参数都是可选的，如果没设置，那么默认会探测使用一个有效的签名：
+
+```bash
+$ xmake l utils.ipa.resign test.ipa
+$ xmake l utils.ipa.resign test.app "Apple Development: [email protected] (T3NA4MRVPU)"
+$ xmake l utils.ipa.resign test.ipa "Apple Development: [email protected] (T3NA4MRVPU)" iOS Team Provisioning Profile: org.tboox.test" org.tboox.test
+```
+
+### 运行应用程序 {#run-program}
+
+目前仅支持运行 macOS 程序：
+
+```bash
+$ xmake run
+```
+
+效果如下：
+
+![](/assets/img/guide/macapp.png)
+
+### 生成程序包 {#package}
+
+如果是 iOS 程序会生成ipa安装包，如果是macos会生成dmg包（dmg包生成暂时还在开发中）。
+
+```bash
+$ xmake package
+output: build/iphoneos/release/arm64/test.ipa
+package ok!
+```
+
+我们也提供了辅助工具，来对指定app程序进行打包：
+
+```bash
+$ xmake l utils.ipa.package test.app output.ipa [iconfile.png]
+```
+
+### 安装 {#install}
+
+如果是iOS程序会安装ipa到设备，如果是macos会安装app到/Applications目录。
+
+```bash
+$ xmake install
+```
+
+我们也提供了辅助工具，来对指定ipa/app程序安装到设备：
+
+```bash
+$ xmake l utils.ipa.install test.app
+$ xmake l utils.ipa.install test.ipa
+```
+
+### 卸载 {#uninstall}
+
+::: tip 注意
+目前仅支持macos程序卸载
+:::
+
+```bash
+$ xmake uninstall
+```
+
+## Framework 库程序 {#Framework}
+
+```lua
+target("test")
+    add_rules("xcode.framework")
+    add_files("src/*.m")
+    add_files("src/Info.plist")
+```
+
+我们也可以通过模板工程快速创建：
+
+```bash
+$ xmake create -t xcode.framework -l objc test
+```
+
+另外，xmake v2.3.9 以上版本，xmake 还提供了带有 framework 库使用的完整 iosapp/macapp 空工程模板，可以完整体验 framework 的编译，依赖使用以及集成到 app 应用程序中。
+
+同时，如果我们开启了模拟器，xmake 可以支持直接 `xmake install` 和 `xmake run` 将 app 安装到模拟器并加载运行。
+
+```bash
+$ xmake create -t xcode.iosapp_with_framework -l objc testapp
+$ cd testapp
+$ xmake f -p iphoneos -a x86_64
+$ xmake
+$ xmake install
+$ xmake run
+```
+
+## Bundle 程序 {#bundle}
+
+```lua
+target("test")
+    add_rules("xcode.bundle")
+    add_files("src/*.m")
+    add_files("src/Info.plist")
+```
+
+我们也可以通过模板工程快速创建：
+
+```bash
+$ xmake create -t xcode.bundle -l objc test
+```