diff --git a/BUILDING.md b/BUILDING.md new file mode 100644 index 00000000..0b3ec362 --- /dev/null +++ b/BUILDING.md @@ -0,0 +1,33 @@ +## Building + +### Prerequisites + +Before building the libraries and samples in this repository, you will need to install [.NET Core](https://dotnet.microsoft.com/download) and the [Cake .NET Core Tool](http://cakebuild.net): + +```sh +dotnet tool install -g cake.tool +dotnet tool install -g xamarin.androidbinderator.tool +dotnet tool install -g xamarin.androidx.migration.tool +``` + +> NOTE: If you previously installed any of these tools, be sure to update them to the latest versions. + +For API diffs install `api-tools` + +``` +dotnet tool install -g api-tools +``` + +### Compiling + +You can now build all the packages by running: + +```sh +dotnet cake +``` + +If you are going to make changes to the `config.json`, then you can run the `packages` target to re-generate all the necessary files: + +```sh +dotnet cake --target=packages +``` diff --git a/README.md b/README.md index 58527191..3e27f9b9 100644 --- a/README.md +++ b/README.md @@ -2,101 +2,35 @@ [![GitHub License](https://img.shields.io/badge/license-MIT-lightgrey.svg)](https://github.com/xamarin/AndroidX/blob/master/LICENSE) [![contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/xamarin/AndroidX/issues) -[![GitHub contributors](https://img.shields.io/github/contributors/xamarin/AndroidX.svg)](https://github.com/xamarin/AndroidX/graphs/contributors) [![Build Status](https://dev.azure.com/devdiv/DevDiv/_apis/build/status/Xamarin/Components/AndroidX?branchName=master)](https://dev.azure.com/devdiv/DevDiv/_build/latest?definitionId=12322&branchName=master) +[![GitHub contributors](https://img.shields.io/github/contributors/xamarin/AndroidX.svg)](https://github.com/xamarin/AndroidX/graphs/contributors) +[![Build Status](https://dev.azure.com/devdiv/DevDiv/_apis/build/status/Xamarin/Components/AndroidX?branchName=master)](https://dev.azure.com/devdiv/DevDiv/_build/latest?definitionId=12322&branchName=master) Xamarin creates and maintains Xamarin.Android bindings for AndroidX. - - [What's New in AndroidX](#whats-new-in-androidx) - - [Building](#building) - - [Prerequisites](#prerequisites) - - [Compiling](#compiling) - - [Android Support -> AndroidX Roadmap](#android-support---androidx-roadmap) - - [Goal](#goal) - - [Phases](#phases) - - [Migration Tools / Tasks Source Code](#migration-tools--tasks-source-code) - - [License](#license) - - [Contribution Guidelines](#contribution-guidelines) - - [.NET Foundation](#net-foundation) +## What is AndroidX -## What's New in AndroidX +AndroidX (also called Jetpack) is a major improvement to the original [Android Support Library](https://github.com/xamarin/AndroidSupportComponents). AndroidX packages fully replace the Android Support Library by providing feature parity and new libraries. -AndroidX is a major improvement to the original [Android Support Library](https://github.com/xamarin/AndroidSupportComponents). AndroidX packages fully replace the Android Support Library by providing feature parity and new libraries. +With the release of AndroidX, Android Support is now considered deprecated and will no longer receive new feature updates. Version 28.0.0 is the last release of the Android Support Library. -In addition, AndroidX includes the following features: +## Binding Policies -* All namespaces in AndroidX live in a consistent namespace starting with AndroidX. The Android Support Library namespaces have been mapped into corresponding AndroidX.* namespaces. For a full mapping of all the old classes and build artifacts to the new ones, see the Package Refactoring page. -* Unlike the Android Support Library, AndroidX namespaces are separately maintained and updated. The AndroidX packages use strict Semantic Versioning, starting with version 1.0.0. You can update AndroidX libraries in your project independently. -* Version 28.0.0 is the last release of the Android Support Library. There will be no more Android Support library releases. All new feature development will be in the AndroidX namespace. - -## Building - -### Prerequisites - -Before building the libraries and samples in this repository, you will need to install [.NET Core](https://dotnet.microsoft.com/download) and the [Cake .NET Core Tool](http://cakebuild.net): - -```sh -dotnet tool install -g cake.tool -dotnet tool install -g xamarin.androidbinderator.tool -dotnet tool install -g xamarin.androidx.migration.tool -``` - -> NOTE: If you previously installed any of these tools, be sure to update them to the latest versions. - -For API diffs install `api-tools` - -``` -dotnet tool install -g api-tools -``` - -### Compiling - -You can now build all the packages by running: - -```sh -dotnet cake -``` - -If you are going to make changes to the `config.json`, then you can run the `packages` target to re-generate all the necessary files: - -```sh -dotnet cake --target=packages -``` - -## Android Support -> AndroidX Roadmap - -With the release of AndroidX, Android Support is now considered deprecated and will no longer receive new feature updates. We are committed to helping our developers bring their applications into this new world with minimal effort. - -### Goal - -Our goal is to allow developers to take an existing application using Android Support libraries, and reference, build, and run against AndroidX libraries without any code changes. - -### Phases - -**1. Xamarin Bindings / NuGet Packages for AndroidX** - -Provide bindings to all of the new AndroidX packages for Xamarin developers. If you want to migrate your app's code manually to use the new AndroidX API's you can reference these packages. Keep in mind that all of your app's dependencies must also be compiled against AndroidX bindings to use these. - -**2. Tooling for Building apps and dependencies with AndroidX** - -Implement build tasks in the AndroidX packages to allow your application to utilize AndroidX without any code changes: - - Dependencies (.NET as well as binding libraries with java and resources in them) will be migrated to the new API's and cached during your first build - - Your app's compiled code will be migrated to the new API's before the application is packaged - - Your app's resource and manifest files will be migrated at build time before the application is packaged - -**3. Optional One Time Migration Tool** - -If your app's code (C#, Resources, Manifest, etc) has not been migrated from Android Support, your build times will be slightly longer. - -We will provide a migration assistant to help convert your C# code, xml resources, and AndroidManifest to use the new AndroidX API's which you can optionally use to perform a one time migration of your project. - -## Migration Tools / Tasks Source Code - -The source code for the `Xamarin.AndroidX.Migration` package and other migration tools and utilities are available in: [source/migration](https://github.com/xamarin/AndroidX/tree/master/source/migration) +- This repository binds over 100 AndroidX libraries that are published to [NuGet.org](https://nuget.org). The full package list can be found in [config.json](config.json). +- AndroidX Java artifacts come from [Google's Maven Respository](https://maven.google.com/web/index.html#). +- Google's release notes for AndroidX libraries are available [here](https://developer.android.com/jetpack/androidx/versions/stable-channel). +- The major/minor/patch version numbers mirror the AndroidX library version. For example, the NuGet `Xamarin.AndroidX.Core 1.3.2.1` binds version `1.3.2` of the AndroidX library `androidx.core:core`. + - The revision version number is used when a new NuGet needs to be built but the AndroidX library has not been updated. +- We endeavor to release updated NuGets within a few weeks after new AndroidX releases, however large changes occasionally require more time. +- In general, we do not bind pre-release libraries. As their API is not stable yet, it results in too much rework. ## License The license for this repository is specified in [LICENSE.md](LICENSE.md) +## Building + +Instructions for building this repository are specified in [BUILDING.md](BUILDING.md) + ## Contribution Guidelines The Contribution Guidelines for this repository are listed in [CONTRIBUTING.md](.github/CONTRIBUTING.md)