Create tooling API model for native domain

[lacasseio]

As the native plugins are getting closer to be stable, more are more users will rely on ways to query the native model to extend or use it either through plugins or the tooling API.

Expected Behavior

Users should be able to query all information about the choice Gradle made during configuration without relying on internal API.

Current Behavior

No tooling API model exists for the native domain. Some information is unavailable to query such as the toolchain tool executable name configuration, while others require more processing like includes path as nothing prevent a user from specifying them as compiler flags.

Contract

• Query components (C++ library or application)
• Query buildable targets for each components
  • Query compiler details for each targets
    • User header search paths (CppCompile#getIncludes(), -I flags, -iquote` flags)
    • System headers search paths (CppCompile#getSystemIncludes() -isystem flags)
    • Framework search paths on macOS only (-F)
    • Defines and undefines (CppCompile#getMacros(), -D flags, -U flags)
    • Extra compiler flags outside of the macros, framework search path, and header search paths)
    • Compilation Gradle task path
    • Compiler tool path used for the compilation as well as the working directory. Note: the user could probably infer the working directory as the getParentFile() of the compiler tool File.
    • Compilation units for the target (CppCompile#getSources())
    • Output location for each source file
    • Headers for the target (public and private)
  • Query linker/create details for each targets. Most importantly executables, then shared libraries and finally maybe of less importance static libraries.
    • Linked or created file location (AbstractLinkTask#getLinkedFile() or CreateStaticLibrary#getBinaryFile())
    • Link or create Gradle task path
  • Component name (CppBinary#getBaseName())
  • Variant name (CppBinary#getName()). Note: this name maybe best without the target name from above included in.
  • Target type (executable, shared library or static library)

[big-guy]

@lacasseio can you add what's needed for the model here?

[zosrothko]

"Should we explicitly deny users from passing compiler/linker flags when a strong model exists? Or should we allow both configurations to coexists with a single query method?" There is always a need for an "escape" mode which could used to match situation not supported/planned by the strong model.

[lacasseio]

Good question @zosrothko. In general, we avoid providing escape hatch and prefer an use case centric solution. This may block unsupported/unplanned situation, however, we have to keep in mind that in Gradle, everything we allow a user to do needs to have tested and be supported. Escape hatch adds a lot of implicit burdens when it comes to maintenance. In our experience, Gradle is flexible enough that you can workaround most limitation in face of an unplanned situation. The best example is the native samples. They offer possibilities around common cases that aren't in the core of Gradle but are still able to make them work.

This issue is centered around the tooling API which allows us to provide a stable API over a less stable model.

[lacasseio]

I updated the description to include what information the tooling API model should be looking at providing.

[vladsoroka]

Could you also expose the information about mapping of source file(*.cpp) and target object(*.o, *.obj) file?
It's planned to be used by CLion to provide visualized output when -fstack-usage compiler option is set.
https://youtrack.jetbrains.com/issue/CPP-13257
(https://gcc.gnu.org/onlinedocs/gnat_ugn/Static-Stack-Usage-Analysis.html)

The current experimental builder uses CompilerOutputFileNamingSchemeFactory project service to obtain the mappings, see details at
https://github.com/JetBrains/intellij-community/blob/0f09427c9e82ed399fbe08f040ac461c109425aa/plugins/gradle/native/tooling/src/builder/CppModelBuilder.java#L163-L184

[adammurdoch]

PR gradle/gradle#6195 adds an initial C++ tooling model plus integration with the new C++ plugins (but not the software model plugins). I think the PR covers most of the stuff listed above.

Something this PR does not handle is any custom compiler args attached to compile tasks. For example, the tooling model builder does not handle extracting the -I compiler args and including the result in the user header path. This is because this isn't well supported in general in the new C++ plugins yet. I've added #803 so that we can fix this for up-to-date checks and caching as well as the IDE integration, rather than just adding a tooling model specific solution.

@vladsoroka would you mind taking a look at the new model and letting us know whether this will work for you? The model will be included in the Gradle 4.10 release but will be incubating. We can make whatever changes you need for 4.11 and we can look at making the APIs stable.

The new model types are here: https://github.com/gradle/gradle/tree/release/subprojects/tooling-api/src/main/java/org/gradle/tooling/model/cpp

The tests are exercising it here: https://github.com/gradle/gradle/tree/release/subprojects/tooling-native/src/crossVersionTest/groovy/org/gradle/language/cpp/tooling/r410

[adammurdoch]

I've closed this issue. We will add new issues for any changes or fixes we need to do.

[adammurdoch]

reopening until the CI coverage for the new project has been set up.

[vladsoroka]

Cool! I'll check the new API asap!

[adammurdoch]

This is done now.

[vladsoroka]

@adammurdoch I've tested the new api using the local dev CLion builds and it looks fine to me. Thank you so much! I will update bundled gradle tooling jars for IDEA/CLion 2018.3 nightly builds when the Gradle 4.10 release will be shipped.