Firefox Android编译入门指导

这篇翻译不完整。请帮忙从英语翻译这篇文章

这个页面只是介绍基础构建 Firefox (Android), 或称之为 Fennec.欢迎使用阅读  :)

如有任何问题,请直接联系 Nick Alexander ( nalexander@mozilla.com ),会尽快回答您的问题.

在Windows系统下构建 Firefox (Android), 需要系统版本 Windows 10 Creator Update 或以上。从Firefox 58以后,你可以使用Win10 自带的Bash( WSL , Windows under Windows Subsystem for Linux ) 进行构建,虽然跟在Linux环境一样,但是还是不推荐,因为不稳定和不支持Android Studio.

更多详细参考 Firefox for Android wikibuild documentation.

准备环境

在折腾Firefox Android代码(代号:Fennec)之前,你需要准备几样东西:

  • 一台电脑或虚拟机,运行 Linux 或 OSX ,至少 30Gb 储存空间.
  • 一台Android设备(或者虚拟设备).
  • 好用的网络.

电脑需要是 64-bit 的 基于Unix的操作系统,你可以输入如下命令确认操作系统是否为 64-bit:

uname -m

... 回车之后, 如果看到 "x86_64" ,说明你操作系统是 64-bit的.

Fennec基本上可以在4年内生产的 Android 设备上运行. 旧的机器,如使用ARMv6 芯片或者更旧可能不被支持.

OK,下一步

Android 设备 的设置

 

你需要为Android设备 "开发者模式",请打开 "设置", 选择 "关于" ,为了激活 "开发者模式",点按 "版本号"7次 ,那么"开发者选项"就会出现在"设置" 菜单中 .

在"开发者选项"中,勾选激活"USB调试",当然你可以随时关闭"USB调试".
电脑 的设置

 

硬件需求

一些硬件上的建议:

  • 更新更好的 CPU. 推荐至少 8GB 内存, 如果硬件比较差推荐编译 artifact mode.
  • 更快的网络. 因为源码提交很大.
  • 64位的操作系统. 32位的操作系统不再被支持.
  • 更新的Android设备,API >=16.
  • 或者使用Android模拟器,可以参考 MozillaWiki .

获取源码

这里使用mercurial 版本控制工具从 Mozilla's Mercurial 下载源码

If your Mercurial version is < 1.5 we recommend that you add the progress extension to your Mercurial configuration. This will provide feedback during the lengthy clone process. See the documentation explaining how to enable the Mercurial progress extension.

如果网络快稳定的话

hg clone https://hg.mozilla.org/mozilla-central

否则你可参考 Mercurial bundle 这种下载方式.

编译依赖项

Note:
1. bootstrap also has a Rust dependency, which requires it to run twice to make the env setup complete. I suggest installing Rust before you run the bootstrap once, then again a second time.
2. If you are a Mac user, you'll need to install Xcode. You'll also need to a) run sudo xcodebuild -license in your terminal or b) manually open Xcode to accept the license before you start the bootstrap process.
3. Please install Java 8 SDK before start the bootstrap. Since Java 9 may cause some error. See bug 1418900
4. Currently Fennec doesn't support instant run. Please disable it before you use Android Studio to build/install Fennec.

5. If you run into proguard.jar related failures, see bug 1408643.

下载好源码后,进入 mozilla-central 目录,执行下面命令(可能需要Python >=2.7 和root 权限或sudo权限):

./mach bootstrap

然后你可以看到下面结果

如果你想修改Firefox 界面等前端工作, 选择3. Firefox for Android Artifact Mode;如果你想修改Firefox内核等后端工作( the back-end 选择 4. Firefox for Android).

bootstrapping 脚本会自动帮你安装好需求包, Android SDK (NDK, 如有必要). 了解 Bootstrap.py 都做了什么事情,可以访问 detailed setup instructions.

接下来根据控制台提示完成配置。

当询问

Would you like to run a configuration wizard to ensure Mercurial is
optimally configured?

  1. Yes
  2. No

如果你想用 git, 可以选择 2. No.

最后bootstrap 脚本会打印出配置内容,如:

Your system should be ready to build Firefox for Android Artifact Mode!


Paste the lines between the chevrons (>>> and <<<) into your
$topsrcdir/mozconfig file, or create the file if it does not exist:

>>>
# Build Firefox for Android Artifact Mode:
ac_add_options --enable-application=mobile/android
ac_add_options --target=arm-linux-androideabi
ac_add_options --enable-artifact-builds


# With the following Android SDK:
ac_add_options --with-android-sdk="/root/.mozbuild/android-sdk-linux"

# Write build artifacts to:
mk_add_options MOZ_OBJDIR=./objdir-frontend
<<<

更多参考下面主题。复制配置内容,如果你忘了(或更改选择)可以重新运行 bootstrap 脚本获取.

Once you have all the dependencies installed, you need to clone the Firefox repository.

选择你想修改的部分

Firefox (Android)有两部分构建内容. 第一部分,称之为“前端” 部分,包括了主页, UI设置, 菜单, 等., Firefox 同步, 和大部分数据储存(用Java编写), Android Platform SDK, JavaScript, HTML, and CSS. 第二部分,后端,构建 Gecko 平台。 Gecko 是 Mozilla 的 网页解析内核, 相当于 Edge, Blink, 和WebKit, 用于解析网页内容 执行JavaScript 代码, 提供页面的 web APIs . Gecko 使用了C++, Rust 和JavaScript.

下面表格是前后端的区别.

Configuration Restrictions Implementation languages Build speed Integrated development environment
front-end Can only modify main UI, not web platform Java, JavaScript Fast builds Android Studio
back-end None: can modify everything C++, Rust, JavaScript Slow builds None: use your text editor
(you can use Android Studio as a fancy text editor and for debugging, though)

Do you want to modify just Firefox for Android, or do you want to modify the Gecko platform?

Note: If you are not sure, start with just the Firefox for Android front-end: your build times will be much shorter if you don't build the Gecko back-end as well.

But don't worry! You can always add the back-end configuration later, and it's easy to switch between the configurations.

配置 mozconfig 文件

mozilla-central 目录下创建 mozconfig 文件. 构建脚本会读取 mozconfig 文件来决定怎么构建代码, 更多参考 although you can configure this if you need to. 必须使用 $HOME 替换 ~ 在 mozconfig 中,因为 ~ 不能被正常解析.

By default, the build system creates a build of Firefox for Android roughly equivalent to the official Firefox for Android Nightly builds. If that's not exactly what you want, there are many build configuration options to choose from. It's strongly recommended that you only use options that you fully understand. Although you may already have your own Android path setup, we strongly recommended you use the version come with above steps (bootstrap.py) . This is will prevent Fennec from interfering with your original development environment.

I want to work on the front-end

Firefox for Android supports a fast build mode called artifact mode. (Some mobile team managers call it manager mode since it's particularly helpful if you only write code infrequently.) Artifact mode downloads pre-built C++ components rather than building them locally, trading bandwidth for time.

To use artifact mode, paste the following into your mozconfig file:

# Build Firefox for Android:
ac_add_options --enable-application=mobile/android
ac_add_options --target=arm-linux-androideabi

# With the following Android SDK:
ac_add_options --with-android-sdk="/absolute/path/to/.mozbuild/android-sdk"

# Enable artifact building:
ac_add_options --enable-artifact-builds

# Write build artifacts to:
mk_add_options MOZ_OBJDIR=./objdir-frontend

Make sure you edit the path for Android SDK accordingly in the above config.

You should be ready to build with artifact mode!

I want to work on the back-end

Important: mach bootstrap currently fails to install rust cross-compile dependencies. See bug 1384231 for updates and a workaround.

Paste the following into your mozconfig file:

# Build Firefox for Android:
ac_add_options --enable-application=mobile/android
ac_add_options --target=arm-linux-androideabi

# With the following Android SDK and NDK:
ac_add_options --with-android-sdk="/absolute/path/to/.mozbuild/android-sdk"
ac_add_options --with-android-ndk="/absolute/path/to/.mozbuild/android-ndk-r15c" 

# Write build artifacts to:
mk_add_options MOZ_OBJDIR=./objdir-droid

Ensure that the Android NDK you've specified (r15c in the example above) matches what you have installed locally.

If you're planning on hacking the C/C++ code, you probably want to create a debug build instead of a release build. Add the following lines to your mozconfig:

ac_add_options --enable-debug
ac_add_options --enable-debug-symbols

Configuration options

I want to build an x86 version of Firefox for Android

Important: Only API versions 15+ are supported on x86 architecture.

Important: Hardware acceleration for Android emulators may not work within virtual machines even if nested virtualization is enabled.

Version 23 and later Android x86 emulators with hardware acceleration are fast enough for local development. They're an attractive alternative if you have recent hardware and an old Android device (or no Android device). Both artifact mode and regular mode support building APKs for x86 architectures. Just replace the line ac_add_options --target=arm-linux-androideabi with:

ac_add_options --target=i386-linux-android

(You probably want to change the MOZ_OBJDIR directory, too.) Now when you build, you should produce an x86 version of Firefox for Android!

For more configuration options, see the general Firefox documentation on configuring build options.

Deploy Firefox to an Android device

Quick start

The bare minimum: run these commands to build, package, install, and run a fresh Firefox for Android on your Android device.

./mach build
./mach package
./mach install
./mach run

Build

Enter the mozilla-central subdirectory (created by the hg clone command).

To build Firefox for Android (compile and link all C/C++, Java, and JavaScript source code), run:

./mach build

Building can take a significant amount of time, depending on your hardware, OS, and chosen build options. Linux builds on a fast box may take under 15 minutes, but builds on a slow machine may take several hours. If you're using artifact mode, builds should take less than five minutes. See tips for making builds faster.

Note: The first time you run mach build, mach will ask you if you'd like to create a .mozbuild directory in your home folder and wait 20 seconds for your answer. This a good default location and you should allow it to create the directory.

Rebuild

To build after making changes, run:

./mach build

This will only rebuild what is necessary for these changes. It is also possible to use:

./mach build mobile/android

This will build any altered Firefox for Android front-end code. If you are using artifact mode, this should always work. If you are building the Gecko back-end, this may yield incorrect results, so it is not recommended.

Package

Running an Android application on a device is a little more involved than running a Desktop Firefox binary. First, we need to package everything into an Android package. To produce an APK, run:

./mach package

The produced APK file can be found in your $OBJDIR/dist folder, and will be called something like fennec-56.0a1.en-US.android-arm.apk.

Install and run

To install the Android package to your device and launch it, connect your Android device and enable USB debugging, and then run the following:

./mach install
./mach run

The name of the App that appears on your Android device will be "Fennec $USER", where $USER is the username under which you built the code.

Note: You will need a device running Android Ice Cream Sandwich (API 15) or later.

While Compiling....

Setting yourself up

The compilation step can take some time. While it’s finishing, you should take a moment to sign up for a Bugzilla account!

Bugzilla.mozilla.org is Mozilla’s issue tracker. To comment on a bug or submit a patch you’ll need a Bugzilla account, so sign up for one now!

As well as Bugzilla, much of Mozilla’s internal communication happens over IRC. You can download Limechat here, and learn how to connect to Mozilla with IRC here. If you’re just getting started or have questions about getting set up you can join us in the #introduction channel, where some of our community members hang out to try and help new contributors get started.

Join Mozillians.org!

There’s one more thing you can do for yourself while you’re waiting: create an account for yourself on Mozillians.

Mozillians is the Mozilla community directory, where you can connect with people who share your interests, projects or countries. This step is optional, but we think it will be worth your while.

Now the fun starts

You’re ready to start hacking. You have the code, you’ve compiled Firefox, and it’s running on your phone. The next steps are up to you: join us on IRC in #introduction and find yourself a bug to work on!

Thank you

Mozilla's strength is the community behind it; Firefox is the product of a global development team working to keep the Web free, open and participatory, and your contributions will make Firefox and the Web better for hundreds of millions of people around the world.

Developing Firefox for Android in Android Studio

Download Android Studio from developer.android.com. The Firefox for Android front-end team develop the product in Android Studio. There is a Gradle build configuration, parallel to the mach build configuration. Eventually, we intend to use Gradle in the mach build configuration.

The Gradle configuration is now "in the source directory". To verify that everything is working, ensure that you've built and packaged successfully, and then run:

./mach gradle clean app:assembleLocalWithGeckoBinariesMinApi21PhotonDebug

Next, simply import the top source directory (mozilla-central, as produced by hg clone) into Android Studio. If Android Studio asks you whether you want to update the Gradle Plugin, choose Don't remind me again for this project, as changing to a newer Gradle version on your own may cause problems with your build. You should now have a shiny new Gradle-based project in Android Studio! Try it out by choosing Build > Rebuild project.

It should look something like:

Choose "Import from Gradle".

Choose the top source directory.

The IDE shows several projects after importing the top source directory.

 

Setting the Run/Debug Configuration and Build Variant

The Gradle build configuration may contain more than one Gradle module, which can define many Run/Debug Configurations. You want the "app" Run Configuration:

Choose "app" from the Run Configurations list.

See the documentation for more.

The configuration also defines multiple Product Flavors, which contribute to Build Variants. You want one of the following combinations, depending on the version of your test device:

Testing device or emulator Android API Product Flavor Build Variant
>=21 localMinApi21 localWithGeckoBinariesMinApi21PhotonDebug
<21 localNoMinApi localWithGeckoBinariesNoMinApiPhotonDebug

Choose "local" if you have an Android 21+ device; choose "localOld" if you have an Android &lt;21 device.

See the Google build documentation for more.

Things that are supported in the IDE

  • Running, debugging, and profiling Firefox for Android in the IDE. The app project defines the Android Application.
    • This includes debugging native code through LLDB - under Run / Edit Configurations… on the Debugger tab, you can switch the Debug type to "Native", add your object directory to the Symbol Directories list, and then start debugging Firefox via Run / Debug 'app' (attaching to an already running Firefox instance might not work).
  • Editing Java source code under mobile/android. Modifications to any of the Java code should prompt a fresh build and install.
  • Editing Android resources under mobile/android, including in mobile/android/base/resources. In many cases the Android Layout Editor is fully functional.
  • Modifying the Android string definitions in mobile/android/base/strings.xml.in and mobile/android/base/locales/en-US/*.dtd. Modifications should be picked up at the next build; they may not be noticed automatically. (This is because the Android strings.xml file is generated, and the generation only happens in response to a build.)
  • Editing "omnijar" JavaScript source code under mobile/android, including in mobile/android/content, mobile/android/components, and mobile/android/modules, and under toolkit/. Modifications to JavaScript code should be picked up at the next build. Such modifications should rebuild the omnijar and prompt a fresh build and install.
  • Editing "omnijar" chrome XHTML, CSS, and JS resources under mobile/android, including in mobile/android/content, and under toolkit/.

Things that are not supported in the IDE

  • Modifying build system configuration and definitions and modifying mobile/android/base/AndroidManifest.xml.in or the sub-manifests. See bug 1221344 for an example of what can go wrong here.
  • Modifying generated Java code such as mobile/android/base/java/org/mozilla/gecko/AppConstants.java.in.
  • Modifying C++ source code anywhere in the tree.
  • Modifying "omnijar" JavaScript source code outside of mobile/android. (If you modify JavaScript outside of mobile/android, say under dom/, the changes will be recognized the next time "omnijar" files inside mobile/android are edited.)
  • Running Robocop tests. (Use mach robocop to run these tests locally.)
  • Running mochitest-chrome tests. (Use mach test to run these tests locally.)

Troubleshooting

  • First, check if the Gradle configuration is working:

    ./mach gradle clean app:assembleLocalWithGeckoBinariesMinApi21PhotonDebug

    That should complete successfully.

  • Second, check that you're building the correct Gradle module and the correct build variant. If you see a runtime error like

    A/GeckoLoader: Couldn't load mozglue. Trying native library dir.
    A/GeckoLoader: Library doesn't exist when it should.
    
    then you are probably running the "automation" Build Variant. See the documentation on Build Variants and the discussion in bug 1246055.
  • Third, ensure that you can install the APK to your device:

    ./gradlew clean app:installLocalWithGeckoBinaries{MinApi21,NoMinApi}PhotonDebug

    This should complete successfully, where you choose "MinApi21" or "NoMinApi" depending on your target device. See the documentation on Build Variants.

  • It's possible to confuse the IDE about the state of the source directory. To recover, try the following:
    • Select the root project and refresh everything in the IDE.
    • Open the root build.gradle file. If the IDE warns that the Gradle configuration has changed, accept the offer to Sync now.
    • Refresh the Gradle model manually: select View > Tool Windows > Gradle and click the blue Sync button in the top left. In Android Studio, there's an icon to do this in the main toolbar -- it's labeled Sync Project with Gradle Files.
    • Clear the IDE cache manually: select File > Invalidate caches and then restart the IDE. (This should never be necessary.)

If you get an error about accepting license agreements during the build, like:

You have not accepted the license agreements of the following SDK components: [Android SDK Build-Tools 25.0.3].
Before building your project, you need to accept the license agreements and complete the installation of the missing components using the Android Studio SDK Manager.

You can fix this error and accept the agreements by running /absolute/path/to/.mozbuild/android-sdk/tools/bin/sdkmanager --licenses. Look in the --with-android-sdk section of your mozconfig file to find the correct path.

Required Android SDK and NDK versions

The Fennec build system requires the following versions:

If your build fails because you're missing one of the Android or Google requirements, your first step should be to run mach bootstrap. If you don't want to run the bootstrapper, you can manually install by running the Android SDK manager: try mach android, or $ANDROID_SDK/tools/android, or use the GUI through Android Studio's settings.

Requirement Version required
Android SDK Platform Android 8.0 (API 26)
SDK Build Tools 26.0.2
SDK Platform Tools current version (27.0.1)
Android SDK Tools current version (26.1.1)
Android Support Repository current version (47 or later)
Google Repository current version (58 or later)
Android NDK r15c

bug 1207680 tracks listing these version requirements in one place in the source code.

文档标签和贡献者

此页面的贡献者: tcg2008, john0804tin
最后编辑者: tcg2008,