Skip to content

Commit 38496cf

Browse files
jonpryordavidbritch
jonpryor
and
davidbritch
authored
[android] Split up the Build Process docs (#1833)
* [android] Split up the Build Process docs When answering Xamarin.Android questions, frequently want to link to the relevant MSBuild property...and *can't*, because all of the MSBuild properties are bulleted items. They're un-linkable. Additionally, the `build-process.md` documentation is *huge*, and increasingly unwieldy because of its size. Split up `build-process.md` into the following files, turning what was previously a bulleted item into a `##` heading, facilitating linking: * `build-items.md`: Supported MSBuild item groups for Builds * `build-properties.md`: Supported MSBuild properties for Builds * `build-targets.md`: Additional MSBuild targets * Update build-items.md * Update build-targets.md Co-authored-by: David Britch <davidbritch@users.noreply.github.com>
1 parent 2d41e28 commit 38496cf

File tree

6 files changed

+1769
-1423
lines changed

6 files changed

+1769
-1423
lines changed

‎docs/android/TOC.yml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -526,6 +526,12 @@
526526
items:
527527
- name: Build Process
528528
href: deploy-test/building-apps/build-process.md
529+
- name: Build Items
530+
href: deploy-test/building-apps/build-items.md
531+
- name: Build Properties
532+
href: deploy-test/building-apps/build-properties.md
533+
- name: Build Targets
534+
href: deploy-test/building-apps/build-targets.md
529535
- name: Building ABI-Specific APKs
530536
href: deploy-test/building-apps/abi-specific-apks.md
531537
- name: Command Line Emulator

‎docs/android/deploy-test/building-apps/build-items.md

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
---
2+
title: "Build Items"
3+
description: "This document will list all supported item groups in the Xamarin.Android build process."
4+
ms.prod: xamarin
5+
ms.assetid: 5EBEE1A5-3879-45DD-B1DE-5CD4327C2656
6+
ms.technology: xamarin-android
7+
author: jonpryor
8+
ms.author: jopryo
9+
ms.date: 09/23/2020
10+
---
11+
12+
# Build Items
13+
14+
Build items control how a Xamarin.Android application
15+
or library project is built.
16+
17+
## AndroidAsset
18+
19+
Supports [Android Assets](https://developer.android.com/guide/topics/resources/providing-resources#OriginalFiles),
20+
files that would be included in the `assets` folder in a Java Android project.
21+
22+
## AndroidAarLibrary
23+
24+
The Build action of `AndroidAarLibrary` should be used to directly
25+
reference `.aar` files. This build action will be most commonly used
26+
by Xamarin Components. Namely to include references to `.aar` files
27+
which are required to get Google Play and other services working.
28+
29+
Files with this Build action will be treated in a similar fashion to
30+
the embedded resources found in Library projects. The `.aar` will be
31+
extracted into the intermediate directory. Then any assets, resource
32+
and `.jar` files will be included in the appropriate item groups.
33+
34+
## AndroidAotProfile
35+
36+
Used to provide an AOT profile, for use with profile-guided AOT.
37+
38+
## AndroidBoundLayout
39+
40+
Indicates that the layout file is to have code-behind generated for it in case when
41+
the `AndroidGenerateLayoutBindings` property is set to `false`. In all other aspects
42+
it is identical to `AndroidResource` described above. This action can be used **only**
43+
with layout files:
44+
45+
```xml
46+
<AndroidBoundLayout Include="Resources\layout\Main.axml" />
47+
```
48+
49+
## AndroidEnvironment
50+
51+
Files with a Build action of `AndroidEnvironment` are used
52+
to [initialize environment variables and system properties during process startup](~/android/deploy-test/environment.md).
53+
The `AndroidEnvironment` Build action may be applied to
54+
multiple files, and they will be evaluated in no particular order (so don't
55+
specify the same environment variable or system property in multiple
56+
files).
57+
58+
## AndroidFragmentType
59+
60+
Specifies the default fully qualified type to be used for all `<fragment>` layout
61+
elements when generating the layout bindings code. The property defaults to the standard
62+
Android `Android.App.Fragment` type.
63+
64+
## AndroidJavaLibrary
65+
66+
Files with a Build action of `AndroidJavaLibrary` are Java
67+
Archives ( `.jar` files) which will be included in the final Android
68+
package.
69+
70+
## AndroidJavaSource
71+
72+
Files with a Build action of `AndroidJavaSource` are Java source code which
73+
will be included in the final Android package.
74+
75+
## AndroidLintConfig
76+
77+
The Build action 'AndroidLintConfig' should be used in conjunction with the
78+
[`$(AndroidLintEnabled)`](~/android/deploy-test/building-apps/build-properties.md#androidlintenabled)
79+
property. Files with this build action will be merged together and passed to the
80+
android `lint` tooling. They should be XML files which contain information on
81+
which tests to enable and disable.
82+
83+
See the [lint documentation](https://developer.android.com/studio/write/lint)
84+
for more details.
85+
86+
## AndroidNativeLibrary
87+
88+
[Native libraries](~/android/platform/native-libraries.md)
89+
are added to the build by setting their Build action to
90+
`AndroidNativeLibrary`.
91+
92+
Note that since Android supports multiple Application Binary Interfaces
93+
(ABIs), the build system must know which ABI the native library is
94+
built for. There are two ways this can be done:
95+
96+
1. Path "sniffing".
97+
2. Using the `Abi` item attribute.
98+
99+
With path sniffing, the parent directory name of the native library is
100+
used to specify the ABI that the library targets. Thus, if you add
101+
`lib/armeabi-v7a/libfoo.so` to the build, then the ABI will be "sniffed" as
102+
`armeabi-v7a`.
103+
104+
### Item Attribute Name
105+
106+
**Abi** &ndash; Specifies the ABI of the native library.
107+
108+
```xml
109+
<ItemGroup>
110+
<AndroidNativeLibrary Include="path/to/libfoo.so">
111+
<Abi>armeabi-v7a</Abi>
112+
</AndroidNativeLibrary>
113+
</ItemGroup>
114+
```
115+
116+
## AndroidResource
117+
118+
All files with an *AndroidResource* build action are compiled into
119+
Android resources during the build process and made accessible via `$(AndroidResgenFile)`.
120+
121+
```xml
122+
<ItemGroup>
123+
<AndroidResource Include="Resources\values\strings.xml" />
124+
</ItemGroup>
125+
```
126+
127+
More advanced users might perhaps wish to have different resources used in
128+
different configurations but with the same effective path. This can be achieved
129+
by having multiple resource directories and having files with the same relative
130+
paths within these different directories, and using MSBuild conditions to
131+
conditionally include different files in different configurations. For
132+
example:
133+
134+
```xml
135+
<ItemGroup Condition="'$(Configuration)'!='Debug'">
136+
<AndroidResource Include="Resources\values\strings.xml" />
137+
</ItemGroup>
138+
<ItemGroup Condition="'$(Configuration)'=='Debug'">
139+
<AndroidResource Include="Resources-Debug\values\strings.xml"/>
140+
</ItemGroup>
141+
<PropertyGroup>
142+
<MonoAndroidResourcePrefix>Resources;Resources-Debug<MonoAndroidResourcePrefix>
143+
</PropertyGroup>
144+
```
145+
146+
**LogicalName** &ndash; Specifies the resource path explicitly. Allows
147+
&ldquo;aliasing&rdquo; files so that they will be available as multiple
148+
distinct resource names.
149+
150+
```xml
151+
<ItemGroup Condition="'$(Configuration)'!='Debug'">
152+
<AndroidResource Include="Resources/values/strings.xml"/>
153+
</ItemGroup>
154+
<ItemGroup Condition="'$(Configuration)'=='Debug'">
155+
<AndroidResource Include="Resources-Debug/values/strings.xml">
156+
<LogicalName>values/strings.xml</LogicalName>
157+
</AndroidResource>
158+
</ItemGroup>
159+
```
160+
161+
## AndroidResourceAnalysisConfig
162+
163+
The Build action `AndroidResourceAnalysisConfig` marks a file as a
164+
severity level configuration file for the Xamarin Android Designer
165+
layout diagnostics tool. This is currently only used in the layout
166+
editor and not for build messages.
167+
168+
See the [Android Resource Analysis
169+
documentation](https://aka.ms/androidresourceanalysis) for more
170+
details.
171+
172+
Added in Xamarin.Android 10.2.
173+
174+
## Content
175+
176+
The normal `Content` Build action is not supported (as we
177+
haven't figured out how to support it without a possibly costly first-run
178+
step).
179+
180+
Starting in Xamarin.Android 5.1, attempting to use the `@(Content)`
181+
Build action will result in a `XA0101` warning.
182+
183+
## LinkDescription
184+
185+
Files with a *LinkDescription* build action are used to
186+
[control linker behavior](~/cross-platform/deploy-test/linker.md).
187+
188+
## ProguardConfiguration
189+
190+
Files with a *ProguardConfiguration* build action contain options which
191+
are used to control `proguard` behavior. For more information about
192+
this build action, see
193+
[ProGuard](~/android/deploy-test/release-prep/proguard.md).
194+
195+
These files are ignored unless the
196+
[`$(EnableProguard)`](~/android/deploy-test/building-apps/build-properties.md#enableproguard)
197+
MSBuild property is `True`.

0 commit comments

Comments
 (0)