0
# Build System
1
2
Advanced build management for React Native Android projects, including Gradle task selection, build modes, architecture-specific builds, and interactive build configuration.
3
4
## Capabilities
5
6
### Core Build Function
7
8
Direct Gradle build execution with custom arguments and source directory specification.
9
10
```typescript { .api }
11
/**
12
* Execute Gradle build with specified arguments (Internal Function)
13
* Note: This function is internal and not directly exportable from the main package
14
* @param gradleArgs - Array of arguments to pass to Gradle
15
* @param sourceDir - Path to Android source directory
16
*/
17
function build(gradleArgs: string[], sourceDir: string): void;
18
```
19
20
**Note**: This function is internal to the `build-android` command implementation and is not directly exportable from the main package.
21
22
### Gradle Task Management
23
24
Comprehensive Gradle task discovery, parsing, and interactive selection.
25
26
```typescript { .api }
27
/**
28
* Gradle task information structure
29
*/
30
interface GradleTask {
31
/** Gradle task name */
32
task: string;
33
/** Task description from Gradle */
34
description: string;
35
}
36
37
/**
38
* Parse available Gradle tasks from gradle command output
39
* @param taskType - Type of tasks to parse (install or build)
40
* @param text - Raw output from Gradle tasks command
41
* @returns Array of parsed Gradle tasks
42
*/
43
function parseTasksFromGradleFile(taskType: 'install' | 'build', text: string): Array<GradleTask>;
44
45
/**
46
* Get available Gradle tasks for the project
47
* @param taskType - Type of tasks to retrieve (install or build)
48
* @param sourceDir - Android source directory path
49
* @returns Array of available Gradle tasks
50
*/
51
function getGradleTasks(taskType: 'install' | 'build', sourceDir: string): GradleTask[];
52
53
/**
54
* Interactive prompt for Gradle task selection
55
* @param taskType - Type of tasks to select from (install or build)
56
* @param sourceDir - Android source directory path
57
* @returns Promise resolving to selected task name or undefined if cancelled
58
*/
59
async function promptForTaskSelection(
60
taskType: 'install' | 'build',
61
sourceDir: string
62
): Promise<string | undefined>;
63
```
64
65
**Usage Examples:**
66
67
```typescript
68
import { getGradleTasks, promptForTaskSelection } from "@react-native-community/cli-platform-android";
69
70
// Get available build tasks
71
const buildTasks = getGradleTasks('build', './android');
72
console.log("Available build tasks:", buildTasks);
73
74
// Get available install tasks
75
const installTasks = getGradleTasks('install', './android');
76
console.log("Available install tasks:", installTasks);
77
78
// Interactive task selection
79
const selectedTask = await promptForTaskSelection('build', './android');
80
if (selectedTask) {
81
console.log(`Selected task: ${selectedTask}`);
82
}
83
```
84
85
### Task Name Generation
86
87
Automated generation of Gradle task names based on build configuration.
88
89
```typescript { .api }
90
/**
91
* Generate Gradle task names for builds based on configuration
92
* @param appName - Application name from Android configuration
93
* @param mode - Build mode (debug, release, etc.), defaults to 'debug'
94
* @param tasks - Custom task names to use instead of generated ones
95
* @param taskPrefix - Type of task to generate (assemble, install, bundle)
96
* @returns Array of generated Gradle task names
97
*/
98
function getTaskNames(
99
appName: string,
100
mode: BuildFlags['mode'] = 'debug',
101
tasks: BuildFlags['tasks'],
102
taskPrefix: 'assemble' | 'install' | 'bundle',
103
): Array<string>;
104
105
/**
106
* Build configuration flags interface
107
*/
108
interface BuildFlags {
109
/** Build mode/variant (debug, release, staging, etc.) */
110
mode?: string;
111
/** Build only for current device architecture in debug mode */
112
activeArchOnly?: boolean;
113
/** Custom Gradle tasks to run instead of generated ones */
114
tasks?: Array<string>;
115
/** Additional parameters to pass to Gradle */
116
extraParams?: Array<string>;
117
/** Enable interactive build type and flavor selection */
118
interactive?: boolean;
119
}
120
```
121
122
**Usage Examples:**
123
124
```typescript
125
import { getTaskNames } from "@react-native-community/cli-platform-android";
126
127
// Generate assemble tasks for debug build
128
const assembleTasks = getTaskNames("MyApp", "debug", undefined, "assemble");
129
console.log("Assemble tasks:", assembleTasks); // ["assembleDebug"]
130
131
// Generate install tasks for release build
132
const installTasks = getTaskNames("MyApp", "release", undefined, "install");
133
console.log("Install tasks:", installTasks); // ["installRelease"]
134
135
// Generate bundle tasks with custom tasks override
136
const customTasks = ["bundleDebug", "bundleRelease"];
137
const bundleTasks = getTaskNames("MyApp", "debug", customTasks, "bundle");
138
console.log("Bundle tasks:", bundleTasks); // ["bundleDebug", "bundleRelease"]
139
```
140
141
## Build Configuration
142
143
### Build Modes and Variants
144
145
Android builds support multiple modes and variants:
146
147
- **debug**: Development builds with debugging enabled
148
- **release**: Production builds with optimizations
149
- **staging**: Pre-production builds for testing
150
- **Custom variants**: Project-specific build types defined in build.gradle
151
152
### Architecture-Specific Builds
153
154
The `activeArchOnly` flag enables building native libraries only for the current device's architecture, which:
155
- Reduces build time during development
156
- Decreases APK size for testing
157
- Only applies to debug builds (release builds include all architectures)
158
159
### Interactive Build Selection
160
161
When using the `interactive` flag, users can:
162
- Choose from available build types (debug, release, etc.)
163
- Select specific product flavors if defined
164
- Combine build types with flavors for complex configurations
165
166
### Custom Gradle Parameters
167
168
The `extraParams` option allows passing additional arguments to Gradle:
169
170
```typescript
171
// Common extra parameters
172
const extraParams = [
173
"--stacktrace", // Show detailed error traces
174
"--info", // Verbose logging
175
"--parallel", // Enable parallel execution
176
"--daemon", // Use Gradle daemon
177
"--offline" // Work offline
178
];
179
```
180
181
### Task Execution Order
182
183
Gradle tasks execute in dependency order:
184
1. **Clean tasks**: Remove previous build artifacts
185
2. **Compile tasks**: Compile source code and resources
186
3. **Assemble tasks**: Create APK files
187
4. **Install tasks**: Install APK on devices
188
5. **Bundle tasks**: Create Android App Bundle files
189
190
## Error Handling
191
192
The build system includes comprehensive error handling for:
193
194
- **Gradle not found**: Missing or misconfigured Gradle installation
195
- **Android SDK issues**: Missing or invalid Android SDK setup
196
- **Build failures**: Compilation errors and dependency issues
197
- **Device connectivity**: Installation failures on target devices
198
- **Permission issues**: File system and device permissions
199
200
## Advanced Usage
201
202
### Custom Build Workflows
203
204
```typescript
205
import { getGradleTasks, build } from "@react-native-community/cli-platform-android";
206
207
// Get all available tasks
208
const buildTasks = getGradleTasks('build', './android');
209
const installTasks = getGradleTasks('install', './android');
210
211
// Create custom build workflow
212
const customWorkflow = [
213
"clean",
214
"assembleDebug",
215
"installDebug"
216
];
217
218
// Execute custom workflow
219
build(customWorkflow, './android');
220
```
221
222
### Build System Integration
223
224
The build system integrates with:
225
- **React Native CLI**: Automatic build configuration
226
- **Metro Bundler**: JavaScript bundle integration
227
- **Native Modules**: Automatic linking and compilation
228
- **Android Gradle Plugin**: Latest build tools support
229
- **Kotlin/Java**: Multi-language project support