|
1 | 1 | # Compose Compiler Reports to HTML Generator |
2 | 2 |
|
3 | | -A CLI utility to convert Jetpack Compose compiler metrics and reports to beautified 😍 HTML page. |
| 3 | +A utility to convert Jetpack Compose compiler metrics and reports to beautified 😍 HTML page. |
4 | 4 | _Made with ❤️ for Android Developers and Composers_ |
5 | 5 |
|
6 | 6 | [](https://github.com/PatilShreyas/compose-report-to-html/actions/workflows/build.yml) |
7 | 7 | [](https://github.com/PatilShreyas/compose-report-to-html/actions/workflows/release.yml) |
8 | 8 |
|
9 | | -[](https://github.com/PatilShreyas) |
10 | | -[](https://github.com/PatilShreyas/compose-report-to-html/stargazers) |
11 | | -[](https://github.com/PatilShreyas/compose-report-to-html/network/members) |
12 | | -[](https://github.com/PatilShreyas/compose-report-to-html/watchers) |
13 | | -[](https://twitter.com/imShreyasPatil) |
| 9 | +| Distribution | Usage Guide | Install | |
| 10 | +|----------------------|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
| 11 | +| **Gradle Plugin** | [Read](https://patilshreyas.github.io/compose-report-to-html/use/using-gradle-plugin/) | [](https://plugins.gradle.org/plugin/dev.shreyaspatil.compose-compiler-report-generator) | |
| 12 | +| **CLI** | [Read](https://patilshreyas.github.io/compose-report-to-html/use/using-cli/) | [](https://www.npmjs.com/package/compose-report2html) <br> [](https://github.com/patilshreyas/compose-report-to-html/releases/latest/download/composeReport2Html.jar) | |
| 13 | +| **Library Artifact** | [Read](https://patilshreyas.github.io/compose-report-to-html/use/using-utility-as-library/) | [](https://search.maven.org/search?q=g:dev.shreyaspatil.compose-compiler-report-generator) | |
14 | 14 |
|
15 | | -| | **Install** | **Downloads** | |
16 | | -|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
17 | | -| **NPM** | [](https://www.npmjs.com/package/compose-report2html) | [](https://www.npmjs.com/package/compose-report2html) | |
18 | | -| **JAR** | [](https://github.com/patilshreyas/compose-report-to-html/releases/latest/download/composeReport2Html.jar) | [](https://github.com/patilshreyas/compose-report-to-html/releases/latest/download/composeReport2Html.jar) | |
19 | | -| **Maven** | [](https://search.maven.org/search?q=g:dev.shreyaspatil.compose-compiler-report-generator) | |
20 | | - |
21 | | -## 💡 Motivation |
22 | | - |
23 | | -The Compose Compiler plugin can generate reports / metrics around certain compose-specific concepts that can be useful |
24 | | -to understand what is happening with some of your compose code at a fine-grained level. |
25 | | -[_**See this**_](https://github.com/androidx/androidx/blob/androidx-main/compose/compiler/design/compiler-metrics.md). |
26 | | - |
27 | | -This generates reports in `json`, `csv` and `txt` files which are not easily trace-able for developers. |
28 | | -Also, Composable function and class reports becomes large and tedious to check. |
29 | | -This tool parses the reports and metrics generated by Compose compiler and beautifies into a HTML page and intelligently |
30 | | -distinguishes problematic and non-problematic composable functions and classes. |
31 | | - |
32 | | -_This utility doesn't generate Compose Metrics and Reports. First, raw Compose report should be generated from the |
33 | | -Compiler and those generated files should be feed to this utility. By parsing that data, this utility generates the |
34 | | -beautified report._ |
35 | | - |
36 | | -## 🧑💻 Usage |
37 | | - |
38 | | -First, install the CLI utility |
39 | | - |
40 | | -### 1. Install CLI |
41 | | - |
42 | | -To install the CLI utility, there are two ways |
43 | | - |
44 | | -#### 1.1 Directly use `.jar` distribution |
45 | | - |
46 | | -Navigate to the [releases](https://github.com/PatilShreyas/compose-report-to-html/releases) and download the latest JAR |
47 | | -artifact. |
48 | | - |
49 | | -#### 1.2 Install from NPM |
50 | | - |
51 | | -Install the [NPM package](https://www.npmjs.com/package/compose-report2html) for CLI utility. |
52 | | - |
53 | | -```shell |
54 | | -npm install -g compose-report2html |
55 | | -``` |
56 | | - |
57 | | -### 2. Know usage |
58 | | - |
59 | | -Run the commands to know the usage of CLI |
60 | | - |
61 | | -#### 2.1 If using JAR artifact |
62 | | - |
63 | | -```shell |
64 | | -java -jar composeReport2Html.jar -h |
65 | | -``` |
66 | | - |
67 | | -#### 2.2 If using NPM package |
68 | | - |
69 | | -If you have installed CLI utility from NPM package, it can be directly available from Terminal. |
70 | | - |
71 | | -```shell |
72 | | -composeReport2Html -h |
73 | | -``` |
74 | | - |
75 | | -Once you run, here's how it looks. |
76 | | - |
77 | | -```shell |
78 | | -Usage: Compose Compiler Report to HTML Generator ~ v1.0.0-alpha03 options_list |
79 | | -Options: |
80 | | - --applicationName, -app -> Application name (To be displayed in the report) (always required) { String } |
81 | | - --inputDirectory, -i -> Input directory where composable report and metrics are available { String } |
82 | | - --overallStatsFile, -overallStatsReport -> Overall Statistics Metrics JSON files (separated by commas) { String } |
83 | | - --detailedStatsFile, -detailedStatsMetrics -> Detailed Statistics Metrics CSV files (separated by commas) { String } |
84 | | - --composableMetricsFile, -composableMetrics -> Composable Metrics TXT files (separated by commas) { String } |
85 | | - --classMetricsFile, -classMetrics -> Class Metrics TXT files (separated by commas) { String } |
86 | | - --outputDirectory, -o -> Output directory name (always required) { String } |
87 | | - --help, -h -> Usage info |
88 | | -``` |
89 | | -
|
90 | | -### 3. Generate report |
91 | | -
|
92 | | -Make sure to generate Compose compiler metrics and reports as |
93 | | -mentioned [here](https://github.com/androidx/androidx/blob/androidx-main/compose/compiler/design/compiler-metrics.md) |
94 | | -or [this good read article by Chris Banes](https://chris.banes.dev/composable-metrics/). These files are then needed to |
95 | | -this CLI utility to feed the data. |
96 | | -
|
97 | | -To generate the report, provide details related to app, metric and report files and output directory. |
98 | | -
|
99 | | -#### 3.1 When all metric and report files are available in the same directory |
100 | | -
|
101 | | -Assuming report and metrics generated by Compose Compiler are available in one directory then you can specify path to |
102 | | -that directory only and utility will automatically pick files. |
103 | | -
|
104 | | -```shell |
105 | | -java -jar composeReport2Html.jar \ |
106 | | - -app MyAppName \ |
107 | | - -i composable_report \ |
108 | | - -o htmlReportDir |
109 | | -``` |
110 | | -
|
111 | | -#### 3.2 Provide path to individual report and metric files |
112 | | -
|
113 | | -You can provide each metric/report file individually using separate parameters. |
114 | | -
|
115 | | -```shell |
116 | | -java -jar composeReport2Html.jar \ |
117 | | - -app MyAppName \ |
118 | | - -overallStatsReport app_release-module.json \ |
119 | | - -detailedStatsMetrics app_release-composables.csv \ |
120 | | - -composableMetrics app_release-composables.txt \ |
121 | | - -classMetrics app_release-classes.txt \ |
122 | | - -o htmlReportDir |
123 | | -``` |
124 | | -
|
125 | | -_(Multiple files can be provided to the single parameter by separating path with commas)_ |
126 | | -
|
127 | | -***If you're using NPM package, directly use command: `composeReport2Html`***. |
128 | | -
|
129 | | -## Utility as a library |
130 | | -
|
131 | | -This utility is also published as a maven artifact on Maven Central so that you can make use of it as you want to use it |
132 | | -(_For example: automation in CI_). |
133 | | -
|
134 | | -Refer to the Wiki for more information: [**Using this utility as a library**](https://github.com/PatilShreyas/compose-report-to-html/wiki/Using-utility-as-a-library) |
135 | | -
|
136 | | -## 📈 Report Overview |
137 | | -
|
138 | | -Once report is generated, it looks like this. |
139 | | -
|
140 | | -| **Title** | **Preview** | |
141 | | -|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| |
142 | | -| **Brief Statistics** | Generates metrics from `.json` file and represents in tabular format. <br><br>  | |
143 | | -| **Detailed Statistics** | Generates report from `.csv` file and represents in tabular format. <br><br>  | |
144 | | -| **Composable Report** | Parses `-composables.txt` file and separates out composables with and without issues and properly highlights issues associated with them. <br><br>  | |
145 | | -| **Class Report** | Parses `-classes.txt` file and separates out stable and unstable classes out of it and properly highlights issues associated with them. <br><br>  | |
146 | | -
|
147 | | -Right now, work is in progress and more improvements related to the report |
148 | | -will happen in some time. If you have any feedback / suggestions related to |
149 | | -the report, feel free to discuss it (_find discussion link in the below section_). |
| 15 | +**▶️ [Read _official docs_](https://patilshreyas.github.io/compose-report-to-html/) for more information and guide to |
| 16 | +use |
| 17 | +this utility** |
150 | 18 |
|
151 | 19 | ## 🙋♂️ Contribute |
152 | 20 |
|
|
0 commit comments