From 147c8ca7fc8a82123faad610b0f252fa40656035 Mon Sep 17 00:00:00 2001 From: "Jon Thysell (JAUNTY)" Date: Wed, 10 Jun 2020 15:16:07 -0700 Subject: [PATCH 1/6] Autolinking docs --- docs/config.md | 118 +++++++++++++++++++++++++++++ docs/native-modules-autolinking.md | 66 ++++++++++++++++ website/sidebars.json | 2 + 3 files changed, 186 insertions(+) create mode 100644 docs/config.md create mode 100644 docs/native-modules-autolinking.md diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 000000000..f060f0ed3 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,118 @@ +--- +id: config +title: React Native Config Schema +--- + +The CLI command [`npx react-native config`](https://github.com/react-native-community/cli/blob/master/docs/commands.md#config) outputs project and dependencies configuration in JSON format to stdout. + +The following describes the schema for projects and dependencies provided by React Native for Windows + macOS. + +> See the [React Native CLI Platforms doc](https://github.com/react-native-community/cli/blob/master/docs/platforms.md) for a description of the schemas for iOS and Android. + +## Windows Platform + +The schema fields are tagged with the following: + +| Tag | Description | +|:-------|:------------| +| *auto* | Item is always calculated by config. An override file should NEVER provide it. | +| *req* | Item is required. If an override file exists, it MUST provide it. If no override file exists, config will try to calculate it. | +| *opt* | Item is optional. If an override file exists, it MAY provide it. If no override file exists, config may try to calculate it. | + +### projectConfig + +`react-native config` will generate the following JSON for app projects that have a windows implementation, as a target for auto-linking. This is done heurestically, so if the result isn't quite correct, app developers can provide a manual override file: `react-native.config.js`. + +Schema for app projects: + +```js +{ + folder: string, // (auto) Absolute path to the app root folder, determined by react-native config, ex: 'c:\path\to\my-app' + sourceDir: string, // (req) Relative path to the windows implementation under folder, ex: 'windows' + solutionFile: string, // (req) Relative path to the app's VS solution file under sourceDir, ex: 'MyApp.sln' + project: { // (req) + projectFile: string, // (req) Relative path to the VS project file under sourceDir, ex: 'MyApp\MyApp.vcxproj' for 'c:\path\to\my-app\windows\MyApp\MyApp.vcxproj' + projectName: string, // (auto) Name of the project, determined from projectFile, ex: 'MyApp' + projectLang: string, // (auto) Language of the project, cpp or cs, determined from projectFile + projectGuid: string, // (auto) Project identifier, determined from projectFile + }, +} +``` + +Example `react-native.config.js` for a *MyApp*: + +```js +module.exports = { + project: { + windows: { + sourceDir: 'windows', + solutionFile: 'MyApp.sln', + project: { + projectFile: 'MyApp\\MyApp.vcxproj', + }, + }, + }, +}; +``` + +### dependencyConfig + +`react-native config` will generate the following JSON for each native module dependency under node_modules that has a windows implementation, in order to support auto-linking. This is done heurestically, so if the result isn't quite correct, native module developers can provide a manual override file: `react-native.config.js`. + +Schema for dependencies: + +```js +{ + folder: string, // (auto) Absolute path to the module root folder, determined by react-native config, ex: 'c:\path\to\app-name\node_modules\my-module' + sourceDir: string, // (opt, req if projects defined) Relative path to the windows implementation under folder, ex: 'windows' + solutionFile: string, // (opt) Relative path to the module's VS solution file under sourceDir, ex: 'MyModule.sln' + projects: [ // (opt) Array of VS projects that must be added to the consuming app's solution file, so they are built + { + projectFile: string, // (req) Relative path to the VS project file under sourceDir, ex: 'MyModule\MyModule.vcxproj' for 'c:\path\to\app-name\node_modules\my-module\windows\MyModule\MyModule.vcxproj' + directDependency: bool, // (req) Whether to add the project file as a dependency to the consuming app's project file. true for projects that provide native modules + projectName: string, // (auto) Name of the project, determined from projectFile, ex: 'MyModule' + projectLang: string, // (auto) Language of the project, cpp or cs, determined from projectFile + projectGuid: string, // (auto) Project identifier, determined from projectFile + cppHeaders: [], // (opt) Array of cpp header include lines, ie: 'winrt/MyModule.h', to be transformed into '#include ' + cppPackageProviders: [], // (opt) Array of fully qualified cpp IReactPackageProviders, ie: 'MyModule::ReactPackageProvider' + csNamespaces: [], // (opt) Array of cs namespaces, ie: 'MyModule', to be transformed into 'using MyModule;' + csPackageProviders: [], // (opt) Array of fully qualified cs IReactPackageProviders, ie: 'MyModule.ReactPackageProvider' + }, + ], + nugetPackages: [ // (opt) Array of nuget packages including native modules that must be added as a dependency to the consuming app. It can be empty, but by its nature it can't be calculated + { + packageName: string, // (req) Name of the nuget package to install + packageVersion: string, // (req) Version of the nuget package to install + cppHeaders: [], // (req) Array of cpp header include lines, ie: 'winrt/NugetModule.h', to be transformed into '#include ' + cppPackageProviders: [], // (req) Array of fully qualified cpp IReactPackageProviders, ie: 'NugetModule::ReactPackageProvider' + csNamespaces: [], // (req) Array of cs namespaces, ie: 'NugetModule', to be transformed into 'using NugetModule;' + csPackageProviders: [], // (req) Array of fully qualified cs IReactPackageProviders, ie: 'NugetModule.ReactPackageProvider' + }, + ], +} +``` + +Example `react-native.config.js` for a *MyModule*: + +```js +module.exports = { + dependency: { + platforms: { + windows: { + sourceDir: 'windows', + solutionFile: 'MyModule.sln', + projects: [ + { + projectFile: 'MyModule\\MyModule.vcxproj', + directDependency: true, + } + ], + }, + }, + }, +}; +``` + +## MacOS Platform + +*TODO* diff --git a/docs/native-modules-autolinking.md b/docs/native-modules-autolinking.md new file mode 100644 index 000000000..c0af83c6d --- /dev/null +++ b/docs/native-modules-autolinking.md @@ -0,0 +1,66 @@ +--- +id: native-modules-autolinking +title: Autolinking Native Modules +--- + +Autolinking is a mechanism that allows your React Native app project to discover and use native modules and view managers provided by React Native libraries. + +This document covers autolinking for the Windows and macOS platforms. It is an extension to the [React Native CLI Autolinking doc](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). + +Add a library using your favorite package manager and run the build: + +``` +yarn add react-native-webview +npx react-native run-windows +``` + +That's it. No more editing native files to use native code. + +## How does it work + +From the [React Native CLI Autolinking doc](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md#how-does-it-work): + +> Each platform defines its own [`platforms`](https://github.com/react-native-community/cli/blob/master/docs/platforms.md) configuration. It instructs the CLI on how to find information about native dependencies. This information is exposed through the [`config`](https://github.com/react-native-community/cli/blob/master/docs/commands.md#config) command in a JSON format. It's then used by the scripts run by the platform's build tools. Each script applies the logic to link native dependencies specific to its platform. + +The information provided by `config` is described in [React Native Config Schema](config.md). + +### Windows Platform + +Autolinking is performed automatically as a part of the `run-windows` command: + +1. At build time, autolinking is performed first, before `msbuild.exe` is invoked and the build actually started. It uses the information provided by `config` to both generate and modify certain native files consumed by your app project. + 1. The `AutolinkedNativeModules.g.targets` file contains the necessary references to the dependency projects that must be built. + > Your app's solution file may also be modified to ensure the dependency projects will be built. + + 1. The `AutolinkedNativeModules.g.(cpp|cs)` files contain a `RegisterAutolinkedNativeModulePackages` method which will add all of the necessary `IReactPackageProvider` from the dependencies to the passed in vector. +1. At build time, while `msbuild.exe` is running, but before compiling your app project, a check will verify that the autolinked files are up-to-date, and warn you if they aren't. + > If you're using `run-windows` this check should always pass. However, if you've manually edited the generated files, or changed your npm dependencies and are building manually with Visual Studio, then the check might fail. See [manually run autolinking](#manually-run-autolinking). +1. At runtime, when your app is starting up it will call `RegisterAutolinkedNativeModulePackages`, registering the native dependencies with React Native, making them available to JS code. + +#### Manually run autolinking + +If you would like to run the autolinking process outside of the build, you can use the `autolink-windows` CLI command, ie: + +```cmd +npx react-native autolink-windows +``` + +| Options | | +|:--------|:-| +| --logging | Verbose output logging | +| --check | Only check whether any autolinked files need to change | +| --sln [string] | Override the app solution file determined by 'react-native config', e.g. windows\myApp.sln | +| --proj [string] | Override the app project file determined by 'react-native config', e.g. windows\myApp\myApp.vcxproj | +| -h, --help | output usage information | + +#### Skipping autolinking + +If you would like to skip the autolinking process during `run-windows` you can pass `--no-autolink` option: + +```cmd +npx react-native run-windows --no-autolink +``` + +### MacOS Platform + +Autolinking is not yet supported for the macOS platform. diff --git a/website/sidebars.json b/website/sidebars.json index ffd77fba8..e6769efce 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -4,6 +4,7 @@ "getting-started", "rnw-dependencies", "parity-status", + "config", "windowsbrush-and-theme" ], "Native Modules (Windows)": [ @@ -11,6 +12,7 @@ "view-managers", "native-modules-setup", "native-modules-using", + "native-modules-autolinking", "native-modules-marshalling-data", "native-modules-jsvalue", "native-modules-advanced" From dfdf247f82ddfc177b3694b60fcc88ffc184ffac Mon Sep 17 00:00:00 2001 From: "Jon Thysell (JAUNTY)" Date: Mon, 15 Jun 2020 17:12:42 -0700 Subject: [PATCH 2/6] Added table for config fields --- docs/config.md | 90 ++++++++++++++++++++---------- docs/native-modules-autolinking.md | 4 +- 2 files changed, 64 insertions(+), 30 deletions(-) diff --git a/docs/config.md b/docs/config.md index f060f0ed3..1693f94c0 100644 --- a/docs/config.md +++ b/docs/config.md @@ -27,18 +27,29 @@ Schema for app projects: ```js { - folder: string, // (auto) Absolute path to the app root folder, determined by react-native config, ex: 'c:\path\to\my-app' - sourceDir: string, // (req) Relative path to the windows implementation under folder, ex: 'windows' - solutionFile: string, // (req) Relative path to the app's VS solution file under sourceDir, ex: 'MyApp.sln' - project: { // (req) - projectFile: string, // (req) Relative path to the VS project file under sourceDir, ex: 'MyApp\MyApp.vcxproj' for 'c:\path\to\my-app\windows\MyApp\MyApp.vcxproj' - projectName: string, // (auto) Name of the project, determined from projectFile, ex: 'MyApp' - projectLang: string, // (auto) Language of the project, cpp or cs, determined from projectFile - projectGuid: string, // (auto) Project identifier, determined from projectFile + folder: string, + sourceDir: string, + solutionFile: string, + project: { + projectFile: string, + projectName: string, + projectLang: string, + projectGuid: string, }, } ``` +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| folder | string | auto | Absolute path to the app root folder, determined by react-native config, ex: *'c:\path\to\my-app'* | +| sourceDir | string | req | Relative path to the windows implementation under folder, ex: *'windows'* | +| solutionFile | string | req | Relative path to the app's VS solution file under sourceDir, ex: *'MyApp.sln'* | +| project | object | req | Object describing the app's VS project: | +| project.projectFile | string | req | Relative path to the VS project file under sourceDir, ex: *'MyApp\MyApp.vcxproj'* for *'c:\path\to\my-app\windows\MyApp\MyApp.vcxproj'* | +| project.projectName | string | auto | Name of the project, determined from projectFile, ex: *'MyApp'* | +| project.projectLang | string | auto | Language of the project, cpp or cs, determined from projectFile | +| project.projectGuid | string | auto | Project identifier, determined from projectFile | + Example `react-native.config.js` for a *MyApp*: ```js @@ -63,35 +74,58 @@ Schema for dependencies: ```js { - folder: string, // (auto) Absolute path to the module root folder, determined by react-native config, ex: 'c:\path\to\app-name\node_modules\my-module' - sourceDir: string, // (opt, req if projects defined) Relative path to the windows implementation under folder, ex: 'windows' - solutionFile: string, // (opt) Relative path to the module's VS solution file under sourceDir, ex: 'MyModule.sln' - projects: [ // (opt) Array of VS projects that must be added to the consuming app's solution file, so they are built + folder: string, + sourceDir: string, + solutionFile: string, + projects: [ { - projectFile: string, // (req) Relative path to the VS project file under sourceDir, ex: 'MyModule\MyModule.vcxproj' for 'c:\path\to\app-name\node_modules\my-module\windows\MyModule\MyModule.vcxproj' - directDependency: bool, // (req) Whether to add the project file as a dependency to the consuming app's project file. true for projects that provide native modules - projectName: string, // (auto) Name of the project, determined from projectFile, ex: 'MyModule' - projectLang: string, // (auto) Language of the project, cpp or cs, determined from projectFile - projectGuid: string, // (auto) Project identifier, determined from projectFile - cppHeaders: [], // (opt) Array of cpp header include lines, ie: 'winrt/MyModule.h', to be transformed into '#include ' - cppPackageProviders: [], // (opt) Array of fully qualified cpp IReactPackageProviders, ie: 'MyModule::ReactPackageProvider' - csNamespaces: [], // (opt) Array of cs namespaces, ie: 'MyModule', to be transformed into 'using MyModule;' - csPackageProviders: [], // (opt) Array of fully qualified cs IReactPackageProviders, ie: 'MyModule.ReactPackageProvider' + projectFile: string, + directDependency: bool, + projectName: string, + projectLang: string, + projectGuid: string, + cppHeaders: [], + cppPackageProviders: [], + csNamespaces: [], + csPackageProviders: [] }, ], - nugetPackages: [ // (opt) Array of nuget packages including native modules that must be added as a dependency to the consuming app. It can be empty, but by its nature it can't be calculated + nugetPackages: [ { - packageName: string, // (req) Name of the nuget package to install - packageVersion: string, // (req) Version of the nuget package to install - cppHeaders: [], // (req) Array of cpp header include lines, ie: 'winrt/NugetModule.h', to be transformed into '#include ' - cppPackageProviders: [], // (req) Array of fully qualified cpp IReactPackageProviders, ie: 'NugetModule::ReactPackageProvider' - csNamespaces: [], // (req) Array of cs namespaces, ie: 'NugetModule', to be transformed into 'using NugetModule;' - csPackageProviders: [], // (req) Array of fully qualified cs IReactPackageProviders, ie: 'NugetModule.ReactPackageProvider' + packageName: string, + packageVersion: string, + cppHeaders: [], + cppPackageProviders: [], + csNamespaces: [], + csPackageProviders: [], }, ], } ``` +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| folder | string | auto | Absolute path to the module root folder, determined by react-native config, ex: *'c:\path\to\app-name\node_modules\my-module'* | +| sourceDir | string | opt, req if projects defined | Relative path to the windows implementation under folder, ex: *'windows'* | +| solutionFile | string | opt | Relative path to the module's VS solution file under sourceDir, ex: *'MyModule.sln'* | +| projects | array | opt | Array of VS projects that must be added to the consuming app's solution file, so they are built | +| projectFile | string | req | Relative path to the VS project file under sourceDir, ex: *'MyModule\MyModule.vcxproj'* for *'c:\path\to\app-name\node_modules\my-module\windows\MyModule\MyModule.vcxproj'* | +| directDependency | bool | req | Whether to add the project file as a dependency to the consuming app's project file. true for projects that provide native modules | +| projectName | string | auto | Name of the project, determined from projectFile, ex: *'MyModule'* | +| projectLang | string | auto | Language of the project, cpp or cs, determined from projectFile | +| projectGuid | string | auto | Project identifier, determined from projectFile | +| cppHeaders | array | opt | Array of cpp header include lines, ie: *'winrt/MyModule.h'*, to be transformed into `#include ` | +| cppPackageProviders | array | opt | Array of fully qualified cpp IReactPackageProviders, ie: *'MyModule::ReactPackageProvider'* | +| csNamespaces | array | opt | Array of cs namespaces, ie: *'MyModule'*, to be transformed into `using MyModule;` | +| csPackageProviders | array | opt | Array of fully qualified cs IReactPackageProviders, ie: *'MyModule.ReactPackageProvider'* | +| nugetPackages | array | opt | Array of nuget packages including native modules that must be added as a dependency to the consuming app. It can be empty, but by its nature it can't be calculated | +| packageName | string | req | Name of the nuget package to install | +| packageVersion | string | req | Version of the nuget package to install | +| cppHeaders | array | req | Array of cpp header include lines, ie: *'winrt/NugetModule.h'*, to be transformed into `#include ` | +| cppPackageProviders | array | req | Array of fully qualified cpp IReactPackageProviders, ie: *'NugetModule::ReactPackageProvider'* | +| csNamespaces | array | req | Array of cs namespaces, ie: *'NugetModule'*, to be transformed into `using NugetModule;` | +| csPackageProviders | array | req | Array of fully qualified cs IReactPackageProviders, ie: *'NugetModule.ReactPackageProvider'* | + Example `react-native.config.js` for a *MyModule*: ```js diff --git a/docs/native-modules-autolinking.md b/docs/native-modules-autolinking.md index c0af83c6d..9fa002fed 100644 --- a/docs/native-modules-autolinking.md +++ b/docs/native-modules-autolinking.md @@ -32,7 +32,7 @@ Autolinking is performed automatically as a part of the `run-windows` command: 1. The `AutolinkedNativeModules.g.targets` file contains the necessary references to the dependency projects that must be built. > Your app's solution file may also be modified to ensure the dependency projects will be built. - 1. The `AutolinkedNativeModules.g.(cpp|cs)` files contain a `RegisterAutolinkedNativeModulePackages` method which will add all of the necessary `IReactPackageProvider` from the dependencies to the passed in vector. + 1. The `AutolinkedNativeModules.g.(cpp|cs)` files contain a `RegisterAutolinkedNativeModulePackages` method which registers all of the specified `IReactPackageProvider`s from the dependencies. 1. At build time, while `msbuild.exe` is running, but before compiling your app project, a check will verify that the autolinked files are up-to-date, and warn you if they aren't. > If you're using `run-windows` this check should always pass. However, if you've manually edited the generated files, or changed your npm dependencies and are building manually with Visual Studio, then the check might fail. See [manually run autolinking](#manually-run-autolinking). 1. At runtime, when your app is starting up it will call `RegisterAutolinkedNativeModulePackages`, registering the native dependencies with React Native, making them available to JS code. @@ -63,4 +63,4 @@ npx react-native run-windows --no-autolink ### MacOS Platform -Autolinking is not yet supported for the macOS platform. +*TODO* From 9893f91fe42093e48ac35b5bbbeaa025295f187e Mon Sep 17 00:00:00 2001 From: "Jon Thysell (JAUNTY)" Date: Tue, 16 Jun 2020 10:41:09 -0700 Subject: [PATCH 3/6] readability improvements --- docs/config.md | 81 +++++++++++++++++++----------- docs/native-modules-autolinking.md | 18 +++---- 2 files changed, 60 insertions(+), 39 deletions(-) diff --git a/docs/config.md b/docs/config.md index 1693f94c0..fd73fe275 100644 --- a/docs/config.md +++ b/docs/config.md @@ -5,12 +5,10 @@ title: React Native Config Schema The CLI command [`npx react-native config`](https://github.com/react-native-community/cli/blob/master/docs/commands.md#config) outputs project and dependencies configuration in JSON format to stdout. -The following describes the schema for projects and dependencies provided by React Native for Windows + macOS. +The following describes the schema for projects and dependencies provided by React Native for Windows. > See the [React Native CLI Platforms doc](https://github.com/react-native-community/cli/blob/master/docs/platforms.md) for a description of the schemas for iOS and Android. -## Windows Platform - The schema fields are tagged with the following: | Tag | Description | @@ -19,11 +17,11 @@ The schema fields are tagged with the following: | *req* | Item is required. If an override file exists, it MUST provide it. If no override file exists, config will try to calculate it. | | *opt* | Item is optional. If an override file exists, it MAY provide it. If no override file exists, config may try to calculate it. | -### projectConfig +## projectConfig `react-native config` will generate the following JSON for app projects that have a windows implementation, as a target for auto-linking. This is done heurestically, so if the result isn't quite correct, app developers can provide a manual override file: `react-native.config.js`. -Schema for app projects: +### Schema: ```js { @@ -39,18 +37,29 @@ Schema for app projects: } ``` +### Top-Level Fields: + +The top-level object has the following fields: + +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| folder | string | auto | Absolute path to the app root folder, determined by `react-native config`, ex: *'c:\path\to\my-app'* | +| sourceDir | string | req | Relative path to the windows implementation under *folder*, ex: *'windows'* | +| solutionFile | string | req | Relative path to the app's VS solution file under *sourceDir*, ex: *'MyApp.sln'* | +| project | object | req | Object describing the app's VS project | + +### Project Object Fields: + +The top-level `project` has the following fields: + | Field | Type | Tag | Description | |:------|:----:|:----:|:------------| -| folder | string | auto | Absolute path to the app root folder, determined by react-native config, ex: *'c:\path\to\my-app'* | -| sourceDir | string | req | Relative path to the windows implementation under folder, ex: *'windows'* | -| solutionFile | string | req | Relative path to the app's VS solution file under sourceDir, ex: *'MyApp.sln'* | -| project | object | req | Object describing the app's VS project: | -| project.projectFile | string | req | Relative path to the VS project file under sourceDir, ex: *'MyApp\MyApp.vcxproj'* for *'c:\path\to\my-app\windows\MyApp\MyApp.vcxproj'* | -| project.projectName | string | auto | Name of the project, determined from projectFile, ex: *'MyApp'* | -| project.projectLang | string | auto | Language of the project, cpp or cs, determined from projectFile | -| project.projectGuid | string | auto | Project identifier, determined from projectFile | +| projectFile | string | req | Relative path to the VS project file under *sourceDir*, ex: *'MyApp\MyApp.vcxproj'* for *'c:\path\to\my-app\windows\MyApp\MyApp.vcxproj'* | +| projectName | string | auto | Name of the project, determined from *projectFile*, ex: *'MyApp'* | +| projectLang | string | auto | Language of the project, cpp or cs, determined from *projectFile* | +| projectGuid | string | auto | Project identifier, determined from *projectFile* | -Example `react-native.config.js` for a *MyApp*: +### Example `react-native.config.js` for a *MyApp*: ```js module.exports = { @@ -66,11 +75,11 @@ module.exports = { }; ``` -### dependencyConfig +## dependencyConfig `react-native config` will generate the following JSON for each native module dependency under node_modules that has a windows implementation, in order to support auto-linking. This is done heurestically, so if the result isn't quite correct, native module developers can provide a manual override file: `react-native.config.js`. -Schema for dependencies: +### Schema: ```js { @@ -103,22 +112,40 @@ Schema for dependencies: } ``` +### Top-Level Fields: + +The top-level object has the following fields: + | Field | Type | Tag | Description | |:------|:----:|:----:|:------------| -| folder | string | auto | Absolute path to the module root folder, determined by react-native config, ex: *'c:\path\to\app-name\node_modules\my-module'* | -| sourceDir | string | opt, req if projects defined | Relative path to the windows implementation under folder, ex: *'windows'* | -| solutionFile | string | opt | Relative path to the module's VS solution file under sourceDir, ex: *'MyModule.sln'* | +| folder | string | auto | Absolute path to the module root folder, determined by `react-native config`, ex: *'c:\path\to\app-name\node_modules\my-module'* | +| sourceDir | string | opt, req if projects defined | Relative path to the windows implementation under *folder*, ex: *'windows'* | +| solutionFile | string | opt | Relative path to the module's VS solution file under *sourceDir*, ex: *'MyModule.sln'* | | projects | array | opt | Array of VS projects that must be added to the consuming app's solution file, so they are built | -| projectFile | string | req | Relative path to the VS project file under sourceDir, ex: *'MyModule\MyModule.vcxproj'* for *'c:\path\to\app-name\node_modules\my-module\windows\MyModule\MyModule.vcxproj'* | +| nugetPackages | array | opt | Array of nuget packages including native modules that must be added as a dependency to the consuming app. It can be empty, but by its nature it can't be calculated | + +### Project Object Fields: + +Objects in the `projects` array have the following fields: + +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| +| projectFile | string | req | Relative path to the VS project file under *sourceDir*, ex: *'MyModule\MyModule.vcxproj'* for *'c:\path\to\app-name\node_modules\my-module\windows\MyModule\MyModule.vcxproj'* | | directDependency | bool | req | Whether to add the project file as a dependency to the consuming app's project file. true for projects that provide native modules | -| projectName | string | auto | Name of the project, determined from projectFile, ex: *'MyModule'* | -| projectLang | string | auto | Language of the project, cpp or cs, determined from projectFile | -| projectGuid | string | auto | Project identifier, determined from projectFile | +| projectName | string | auto | Name of the project, determined from *projectFile*, ex: *'MyModule'* | +| projectLang | string | auto | Language of the project, cpp or cs, determined from *projectFile* | +| projectGuid | string | auto | Project identifier, determined from *projectFile* | | cppHeaders | array | opt | Array of cpp header include lines, ie: *'winrt/MyModule.h'*, to be transformed into `#include ` | | cppPackageProviders | array | opt | Array of fully qualified cpp IReactPackageProviders, ie: *'MyModule::ReactPackageProvider'* | | csNamespaces | array | opt | Array of cs namespaces, ie: *'MyModule'*, to be transformed into `using MyModule;` | | csPackageProviders | array | opt | Array of fully qualified cs IReactPackageProviders, ie: *'MyModule.ReactPackageProvider'* | -| nugetPackages | array | opt | Array of nuget packages including native modules that must be added as a dependency to the consuming app. It can be empty, but by its nature it can't be calculated | + +### Nuget Package Object Fields: + +Objects in the `nugetPackages` array have the following fields: + +| Field | Type | Tag | Description | +|:------|:----:|:----:|:------------| | packageName | string | req | Name of the nuget package to install | | packageVersion | string | req | Version of the nuget package to install | | cppHeaders | array | req | Array of cpp header include lines, ie: *'winrt/NugetModule.h'*, to be transformed into `#include ` | @@ -126,7 +153,7 @@ Schema for dependencies: | csNamespaces | array | req | Array of cs namespaces, ie: *'NugetModule'*, to be transformed into `using NugetModule;` | | csPackageProviders | array | req | Array of fully qualified cs IReactPackageProviders, ie: *'NugetModule.ReactPackageProvider'* | -Example `react-native.config.js` for a *MyModule*: +### Example `react-native.config.js` for a *MyModule*: ```js module.exports = { @@ -146,7 +173,3 @@ module.exports = { }, }; ``` - -## MacOS Platform - -*TODO* diff --git a/docs/native-modules-autolinking.md b/docs/native-modules-autolinking.md index 9fa002fed..6aa2a4b73 100644 --- a/docs/native-modules-autolinking.md +++ b/docs/native-modules-autolinking.md @@ -5,7 +5,7 @@ title: Autolinking Native Modules Autolinking is a mechanism that allows your React Native app project to discover and use native modules and view managers provided by React Native libraries. -This document covers autolinking for the Windows and macOS platforms. It is an extension to the [React Native CLI Autolinking doc](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). +This document covers autolinking for the Windows platform. It is an extension to the [React Native CLI Autolinking doc](https://github.com/react-native-community/cli/blob/master/docs/autolinking.md). Add a library using your favorite package manager and run the build: @@ -24,7 +24,7 @@ From the [React Native CLI Autolinking doc](https://github.com/react-native-comm The information provided by `config` is described in [React Native Config Schema](config.md). -### Windows Platform +## Autolinking process Autolinking is performed automatically as a part of the `run-windows` command: @@ -37,7 +37,9 @@ Autolinking is performed automatically as a part of the `run-windows` command: > If you're using `run-windows` this check should always pass. However, if you've manually edited the generated files, or changed your npm dependencies and are building manually with Visual Studio, then the check might fail. See [manually run autolinking](#manually-run-autolinking). 1. At runtime, when your app is starting up it will call `RegisterAutolinkedNativeModulePackages`, registering the native dependencies with React Native, making them available to JS code. -#### Manually run autolinking +## Alternatives + +### Manually run autolinking If you would like to run the autolinking process outside of the build, you can use the `autolink-windows` CLI command, ie: @@ -49,18 +51,14 @@ npx react-native autolink-windows |:--------|:-| | --logging | Verbose output logging | | --check | Only check whether any autolinked files need to change | -| --sln [string] | Override the app solution file determined by 'react-native config', e.g. windows\myApp.sln | -| --proj [string] | Override the app project file determined by 'react-native config', e.g. windows\myApp\myApp.vcxproj | +| --sln [string] | Override the app solution file determined by `react-native config`, e.g. *windows\myApp.sln* | +| --proj [string] | Override the app project file determined by `react-native config`, e.g. *windows\myApp\myApp.vcxproj* | | -h, --help | output usage information | -#### Skipping autolinking +### Skipping autolinking If you would like to skip the autolinking process during `run-windows` you can pass `--no-autolink` option: ```cmd npx react-native run-windows --no-autolink ``` - -### MacOS Platform - -*TODO* From 2e187219286e9e7f11e6758aedc6612780e82264 Mon Sep 17 00:00:00 2001 From: Jon Thysell Date: Mon, 22 Jun 2020 09:59:23 -0700 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Alexander Sklar --- docs/config.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/config.md b/docs/config.md index fd73fe275..758faeca0 100644 --- a/docs/config.md +++ b/docs/config.md @@ -19,7 +19,7 @@ The schema fields are tagged with the following: ## projectConfig -`react-native config` will generate the following JSON for app projects that have a windows implementation, as a target for auto-linking. This is done heurestically, so if the result isn't quite correct, app developers can provide a manual override file: `react-native.config.js`. +`react-native config` will generate the following JSON for app projects that have a Windows implementation, as a target for auto-linking. This is done heuristically, so if the result isn't quite correct, app developers can provide a manual override file: `react-native.config.js`. ### Schema: @@ -56,7 +56,7 @@ The top-level `project` has the following fields: |:------|:----:|:----:|:------------| | projectFile | string | req | Relative path to the VS project file under *sourceDir*, ex: *'MyApp\MyApp.vcxproj'* for *'c:\path\to\my-app\windows\MyApp\MyApp.vcxproj'* | | projectName | string | auto | Name of the project, determined from *projectFile*, ex: *'MyApp'* | -| projectLang | string | auto | Language of the project, cpp or cs, determined from *projectFile* | +| projectLang | string | auto | Language of the project, `cpp` (for C++) or `cs` (for C#), determined from *projectFile* | | projectGuid | string | auto | Project identifier, determined from *projectFile* | ### Example `react-native.config.js` for a *MyApp*: @@ -77,7 +77,7 @@ module.exports = { ## dependencyConfig -`react-native config` will generate the following JSON for each native module dependency under node_modules that has a windows implementation, in order to support auto-linking. This is done heurestically, so if the result isn't quite correct, native module developers can provide a manual override file: `react-native.config.js`. +`react-native config` will generate the following JSON for each native module dependency under `node_modules` that has a Windows implementation, in order to support auto-linking. This is done heuristically, so if the result isn't quite correct, native module developers can provide a manual override file: `react-native.config.js`. ### Schema: From d35b720c017e43aa05d900f2997efd5d8290ddaf Mon Sep 17 00:00:00 2001 From: "Jon Thysell (JAUNTY)" Date: Wed, 24 Jun 2020 17:25:13 -0700 Subject: [PATCH 5/6] updating exclusions --- website/.unbroken_exclusions | 45 ++++++++++++++++++++++++++++++++---- 1 file changed, 40 insertions(+), 5 deletions(-) diff --git a/website/.unbroken_exclusions b/website/.unbroken_exclusions index e3df07e82..448e9d210 100644 --- a/website/.unbroken_exclusions +++ b/website/.unbroken_exclusions @@ -1,6 +1,46 @@ !node_modules !blog/2019- +File not found building-rnw.md while parsing versioned_docs/version-0.62/getting-started.md +File not found native-modules.md while parsing versioned_docs/version-0.62/getting-started.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/getting-started.md +File not found building-rnw.md while parsing versioned_docs/version-0.62/getting-started.md +File not found native-modules.md while parsing versioned_docs/version-0.62/getting-started.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/getting-started.md +File not found native-modules.md while parsing versioned_docs/version-0.62/IReactModuleBuilder-api-windows.md +File not found native-modules.md while parsing versioned_docs/version-0.62/IReactModuleBuilder-api-windows.md +File not found view-managers.md while parsing versioned_docs/version-0.62/IViewManager-api-windows.md +File not found view-managers.md while parsing versioned_docs/version-0.62/IViewManager-api-windows.md +File not found ikeyboardprops-api-windows.md while parsing versioned_docs/version-0.62/iviewwindowsprops-api-windows.md +File not found native-modules.md while parsing versioned_docs/version-0.62/native-modules-advanced.md +File not found native-modules.md while parsing versioned_docs/version-0.62/native-modules-advanced.md +File not found assets/native-module-dependencies.png while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found assets/native-modules-setup-new-cpp-project.png while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found assets/native-modules-setup-new-cs-project.png while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found assets/native-modules-setup-wrong-cpp-project.png while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found getting-started.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found native-modules.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found view-managers.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found getting-started.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found native-modules-using.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found native-modules.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found project-structure.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found view-managers.md while parsing versioned_docs/version-0.62/native-modules-setup.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.62/native-modules.md +File not found view-managers.md while parsing versioned_docs/version-0.62/native-modules.md +File not found native-modules-advanced.md while parsing versioned_docs/version-0.62/native-modules.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.62/native-modules.md +File not found view-managers.md while parsing versioned_docs/version-0.62/native-modules.md +File not found win10-compat.md while parsing versioned_docs/version-0.62/rnw-dependencies.md +File not found win10-compat.md while parsing versioned_docs/version-0.62/rnw-dependencies.md +File not found getting-started.md while parsing versioned_docs/version-0.62/view-managers.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.62/view-managers.md +File not found native-modules.md while parsing versioned_docs/version-0.62/view-managers.md +File not found getting-started.md while parsing versioned_docs/version-0.62/view-managers.md +File not found native-modules-setup.md while parsing versioned_docs/version-0.62/view-managers.md +File not found native-modules.md while parsing versioned_docs/version-0.62/view-managers.md File not found rnw-dependencies.md while parsing versioned_docs/version-0.61/building-rnw.md File not found building-rnw.md while parsing versioned_docs/version-0.61/getting-started.md File not found native-modules.md while parsing versioned_docs/version-0.61/getting-started.md @@ -25,7 +65,6 @@ File not found native-modules-advanced.md while parsing versioned_docs/version-0 File not found native-modules-setup.md while parsing versioned_docs/version-0.61/native-modules.md File not found view-managers.md while parsing versioned_docs/version-0.61/native-modules.md File not found flyout-component-windows.md while parsing versioned_docs/version-0.61/popup-component-windows.md -File not found e2e-test.md while parsing versioned_docs/version-0.61/rnw-dependencies.md File not found win10-compat.md while parsing versioned_docs/version-0.61/rnw-dependencies.md File not found getting-started.md while parsing versioned_docs/version-0.61/view-managers.md File not found native-modules-setup.md while parsing versioned_docs/version-0.61/view-managers.md @@ -37,7 +76,3 @@ File not found assets/technical-decision.png while parsing versioned_docs/versio File not found assets/wdio-internal-dependencies.png while parsing versioned_docs/version-0.60/e2e-test-more-about.md File not found assets/reveal-surface-animation.gif while parsing versioned_docs/version-0.60/windowsbrush-and-theme.md File not found assets/rnw-acrylic-surface.png while parsing versioned_docs/version-0.60/windowsbrush-and-theme.md -URL not found https://mybuild.microsoft.com/sessions/b1306a79-b43b-43be-bd59-460b8db0c7a8 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) -URL not found https://mybuild.microsoft.com/sessions/d10c502e-325d-4c77-9471-462b37744db1 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) -URL not found https://mybuild.microsoft.com/sessions/53ccd339-7cc0-4e66-bdb9-3eee6b270658 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) -URL not found https://mybuild.microsoft.com/sessions/cf5901a1-2cd2-4913-b4b7-f1af32db934a while parsing blog/2020-06-01-build2020recap.md (HTTP 404) From 8bb9349b6a1485ab319ac3193e9d47bcc72278b3 Mon Sep 17 00:00:00 2001 From: "Jon Thysell (JAUNTY)" Date: Thu, 25 Jun 2020 09:09:03 -0700 Subject: [PATCH 6/6] fix unbroken --- website/.unbroken_exclusions | 5 +++++ website/fix-unbroken.js | 7 +++++++ 2 files changed, 12 insertions(+) diff --git a/website/.unbroken_exclusions b/website/.unbroken_exclusions index 448e9d210..80b3c6321 100644 --- a/website/.unbroken_exclusions +++ b/website/.unbroken_exclusions @@ -1,6 +1,11 @@ !node_modules !blog/2019- +URL not found https://mybuild.microsoft.com/sessions/b1306a79-b43b-43be-bd59-460b8db0c7a8 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) +URL not found https://mybuild.microsoft.com/sessions/d10c502e-325d-4c77-9471-462b37744db1 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) +URL not found https://mybuild.microsoft.com/sessions/53ccd339-7cc0-4e66-bdb9-3eee6b270658 while parsing blog/2020-06-01-build2020recap.md (HTTP 404) +URL not found https://mybuild.microsoft.com/sessions/cf5901a1-2cd2-4913-b4b7-f1af32db934a while parsing blog/2020-06-01-build2020recap.md (HTTP 404) + File not found building-rnw.md while parsing versioned_docs/version-0.62/getting-started.md File not found native-modules.md while parsing versioned_docs/version-0.62/getting-started.md File not found rnw-dependencies.md while parsing versioned_docs/version-0.62/getting-started.md diff --git a/website/fix-unbroken.js b/website/fix-unbroken.js index 2d5e7f6a9..ed15cbb36 100644 --- a/website/fix-unbroken.js +++ b/website/fix-unbroken.js @@ -68,6 +68,13 @@ exclusions.push(normalizePath('!node_modules')); exclusions.push(normalizePath('!blog\\2019-')); exclusions.push(''); +// MyBuild Sessions +exclusions.push('URL not found https://mybuild.microsoft.com/sessions/b1306a79-b43b-43be-bd59-460b8db0c7a8 while parsing blog/2020-06-01-build2020recap.md (HTTP 404)'); +exclusions.push('URL not found https://mybuild.microsoft.com/sessions/d10c502e-325d-4c77-9471-462b37744db1 while parsing blog/2020-06-01-build2020recap.md (HTTP 404)'); +exclusions.push('URL not found https://mybuild.microsoft.com/sessions/53ccd339-7cc0-4e66-bdb9-3eee6b270658 while parsing blog/2020-06-01-build2020recap.md (HTTP 404)'); +exclusions.push('URL not found https://mybuild.microsoft.com/sessions/cf5901a1-2cd2-4913-b4b7-f1af32db934a while parsing blog/2020-06-01-build2020recap.md (HTTP 404)'); +exclusions.push(''); + // Redirected files exclusions redirectedFiles.forEach(redirectedFile => { exclusions.push(`File not found ${normalizePath(redirectedFile.target)} while parsing ${normalizePath(redirectedFile.source)}`);