Apollo-android: Improve documentation for excluding files from the source set

[PHPirates]

Summary

In version 1.* I used exclude("**/schema.graphql") in my Gradle configuration in order to exclude a graphql file that could not be parsed by Apollo. However, since I updated to apollo-android 2.* this option seems not to be available anymore.

Version
2.1.0

Description

I am using apollo-android in a non-android project, using IntelliJ and Kotlin with Kotlin Gradle DSL. I just migrated from 1.2.3 to the plugin version 2.1.0.

My previous setup contained in my build.gradle.kts:

tasks.withType<com.apollographql.apollo.gradle.ApolloCodegenTask> {
    generateKotlinModels.set(true)
    exclude("**/schema.graphql")
}

I needed this, because there is a schema.graphql file which is downloaded automatically when introspecting the GitHub api, and which is required as by https://github.com/jimkyndemeyer/js-graphql-intellij-plugin/issues/305. However, there is a parse error:

Failed to parse GraphQL file /path/to/src/mymodule/schema.graphql (8:0)
Unsupported token `"Represents an object which can take actions on GitHub

Similar to #1360, I also use a schema.json which works fine.

When migrating to 2.1.0, I read https://www.apollographql.com/docs/android/essentials/migration/#gradle-plugin-changes but it does not mention anything about removing the exclude option. Therefore I am not sure whether this is missing in the code or documentation (or both).

The current documentation at https://www.apollographql.com/docs/android/essentials/plugin-configuration/ shows the configuration options, but exclude is not listed there.
Of course it does show a schemaFile option, however when I use it like

apollo {
    schemaFile.set(File("/absolute/path/to/schema.json"))
}

it (that is, the generateMainServiceApolloSources Gradle task) still tries to parse the graphql file and fails.

The relevant part of my build.gradle.kts is as follows

plugins {

    val kotlinVersion = "1.3.72"

    application
    kotlin("jvm") version kotlinVersion
    java
    idea

    id("com.apollographql.apollo") version "2.1.0"
}

dependencies {
    implementation(kotlin("stdlib"))

    // Apollo and dependencies
    implementation("com.apollographql.apollo:apollo-runtime:2.1.0")
    implementation("com.squareup.okio:okio:2.4.3")
    implementation("org.jetbrains:annotations:19.0.0")
    testImplementation("org.jetbrains:annotations:19.0.0")
}

repositories {
    mavenCentral()
    mavenLocal()
    jcenter()
}

apollo {
    generateKotlinModels.set(true)
    exclude("**/schema.graphql")
}

My old setup for 1.2.3 is here: https://stackoverflow.com/a/59776118/4126843

[martinbonnin]

Hi! This changed in version 1.3. The plugin extension now exposes a Gradle SourceDirectorySet named graphqlSourceDirectorySet. You should be able to include/exclude files on this object. Something like:

apollo {
  graphqlSourceDirectorySet.exclude("**/schema.graphql")
}

[PHPirates]

Thanks, I'm not sure why I didn't mention it in the issue, but when I add that I still get the parse error on schema.graphql. I also tried with the full path to the graphql file, and together with setting schemaFile to the json file, and by setting rootPackageName (though these last two were not necessary in 1.2).

You were right about the version though: I have this problem in 1.4.5 and 1.3.3 as well when using the new com.apollographql.apollo plugin.

This is my directory structure, which as far as I know is what apollo android expects:

.
├── build
│   └── generated
│       └── source
│           └── apollo
│               └── main
├── build.gradle.kts
└── src
    └── main
        ├── graphql
        │   └── nl
        │       └── deltadak
        │           └── texifystats
        │               ├── OpenIssues.graphql
        │               ├── schema.graphql
        │               └── schema.json
        └── kotlin
            └── nl
                └── deltadak
                    └── texifystats
                        └── TotalIssuesStatistic.kt

I am using Gradle 6.4.1.

The full project is here: https://github.com/PHPirates/TeXiFy-stats, I may try to build a more minimal example but this project is already fairly minimal.

I also did a Gradle clean to check if that was causing migration issues, but the parse error remains and thus sources are not generated by generateApolloSources.

At least the problem is reproducible on GitHub Actions for the complete project: https://github.com/PHPirates/TeXiFy-stats/runs/727644892

I have my project and Gradle JVM set to Java 13.

[martinbonnin]

This is coming from the fallback not picking up the exclude because the SourceDirectorySet is empty.

You can workaround this by specifying your graphql files explicitely:

    graphqlSourceDirectorySet.srcDir("src/main/graphql")
    graphqlSourceDirectorySet.include("**/*.graphql")
    graphqlSourceDirectorySet.exclude("**/schema.graphql")

This was made to accommodate multiple GraphQL schemas while still allowing the shorthand of adding configuration at the root of the apollo {} block.

The idea was to expose a SourceDirectorySet as it's more flexible than only include/exclude patterns and allows to have arbitrary placed .graphql files but that complicates your use case. I'll think about a way to concile both use cases.

[PHPirates]

Thanks, that solves that problem! I didn't know that had changed as well, it does make sense - it just wasn't clear to me that the previously default now had to be specified as well.

Perhaps it is possible to document this include/exclude behaviour in order to support users of the JS GraphQL plugin? (As far as I know it is needed to have the schema.graphql file for the plugin to work) I mean, currently all the documentation I can see, apart from the migration guide, is in https://www.apollographql.com/docs/android/essentials/plugin-configuration/ and says

  /**
   * The graphql files containing the queries.
   *
   * This SourceDirectorySet includes .graphql and .gql files by default.
   *
   * By default, it will use [Service.sourceFolder] to populate the SourceDirectorySet.
   * You can override it from [ApolloExtension.onCompilationUnit] for more advanced use cases
   */
  val graphqlSourceDirectorySet: SourceDirectorySet

and it is difficult for me to extract from this that I need to do

    graphqlSourceDirectorySet.srcDir("src/main/graphql")
    graphqlSourceDirectorySet.include("**/*.graphql")
    graphqlSourceDirectorySet.exclude("**/schema.graphql")

[martinbonnin]

Yea, agreed this should be more explicit.

Regarding the JS graphql plugin. I think it supports introspection schemas ? With something like this in your .graphqlconfig:

{
  "schema": "src/main/graphql/schema.json"
}

[PHPirates]

I think it should indeed, however (and this may be a particular problem with the GitHub api or with not using Android, I don't know) when I do so I run into this error: https://github.com/jimkyndemeyer/js-graphql-intellij-plugin/issues/305

[martinbonnin]

@PHPirates I made https://github.com/apollographql/apollo-android/pull/2322 to change the documentation. Let me know what you think.