├── .gitignore ├── .gitmodules ├── .jvmopts ├── .scalafmt.conf ├── LICENSE.md ├── README.md ├── bin └── scalafmt ├── build.sbt ├── docs-out ├── assets │ ├── astexplorer.png │ ├── established.png │ ├── foobar.png │ ├── foobar.png.gz │ ├── semantic-api.png │ ├── syntactic-api.png │ └── tree.svg ├── example.scala ├── misc │ ├── built-with-scalameta.md │ └── presentations.md ├── semanticdb │ ├── guide.md │ └── specification.md └── trees │ ├── astexplorer.md │ ├── examples.md │ ├── guide.md │ ├── quasiquotes.md │ ├── scaladoc.md │ └── scalafiddle.md ├── docs ├── assets │ ├── astexplorer.png │ ├── established.png │ ├── foobar.png │ ├── foobar.png.gz │ ├── semantic-api.png │ ├── syntactic-api.png │ └── tree.svg ├── example.scala ├── misc │ ├── built-with-scalameta.md │ └── presentations.md └── trees │ ├── astexplorer.md │ ├── guide.md │ ├── scaladoc.md │ └── scalafiddle.md ├── project ├── build.properties ├── plugins.sbt └── project │ └── plugins.sbt ├── sbt ├── scalameta-docs └── src │ └── main │ └── scala │ └── docs │ ├── LandingPage.scala │ ├── Main.scala │ └── ScalametaDocs.scala ├── tree.dot ├── tree.pdf └── website ├── core └── Footer.js ├── i18n └── en.json ├── package.json ├── pages └── en │ └── index.js ├── sidebars.json ├── siteConfig.js └── static ├── css └── custom.css ├── img ├── favicon.ico └── scalameta.png ├── paradise └── index.html ├── talks ├── 2017-04-21-SemanticToolingAtTwitter.pdf ├── 2017-06-01-SemanticToolingAtTwitter.pdf └── 2018-06-20-HowWeBuiltToolsThatScaleToMillionsOfLoc.pdf └── tutorial └── index.html /.gitignore: -------------------------------------------------------------------------------- 1 | *.class 2 | *.log 3 | 4 | # sbt specific 5 | .cache 6 | .history 7 | .lib/ 8 | dist/* 9 | target/ 10 | lib_managed/ 11 | src_managed/ 12 | project/boot/ 13 | project/plugins/project/ 14 | 15 | # Scala-IDE specific 16 | .scala_dependencies 17 | .worksheet 18 | 19 | .idea 20 | 21 | # ENSIME specific 22 | .ensime_cache/ 23 | .ensime 24 | 25 | 26 | node_modules 27 | 28 | lib/core/metadata.js 29 | lib/core/MetadataBlog.js 30 | 31 | website/translated_docs 32 | website/build/ 33 | website/yarn.lock 34 | website/node_modules 35 | website/i18n/* 36 | !website/i18n/en.json 37 | 38 | out/ 39 | mbrowse/ 40 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/scalameta/tutorial/789a7fe9414d6d98f1f7e8b3a9b2d3b9714d6636/.gitmodules -------------------------------------------------------------------------------- /.jvmopts: -------------------------------------------------------------------------------- 1 | -Xss4m 2 | -Xms1G 3 | -Xmx8G 4 | -XX:ReservedCodeCacheSize=1024m 5 | -XX:+TieredCompilation 6 | -XX:+CMSClassUnloadingEnabled 7 | 8 | -------------------------------------------------------------------------------- /.scalafmt.conf: -------------------------------------------------------------------------------- 1 | project.git = true 2 | align = none 3 | runner.dialect = Dotty # For inline 4 | assumeStandardLibraryStripMargin = true 5 | onTestFailure = "To fix this, run ./bin/scalafmt" 6 | -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | This repository is licensed under the [BSD 3-Clause License](http://opensource.org/licenses/BSD-3-Clause). 2 | 3 | Copyright (c) 2016-2018 EPFL 4 | Copyright (c) 2018 Twitter, Inc. 5 | 6 | All rights reserved. 7 | 8 | Redistribution and use in source and binary forms, with or without modification, 9 | are permitted provided that the following conditions are met: 10 | 11 | * Redistributions of source code must retain the above copyright notice, 12 | this list of conditions and the following disclaimer. 13 | * Redistributions in binary form must reproduce the above copyright notice, 14 | this list of conditions and the following disclaimer in the documentation 15 | and/or other materials provided with the distribution. 16 | * Neither the name of the EPFL nor the names of its contributors 17 | may be used to endorse or promote products derived from this software 18 | without specific prior written permission. 19 | 20 | THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 21 | "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 22 | LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 23 | A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR 24 | CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 25 | EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 26 | PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 27 | PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 28 | LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 29 | NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 30 | SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 31 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | See http://scalameta.org/tutorial/. 2 | -------------------------------------------------------------------------------- /bin/scalafmt: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/scalameta/tutorial/789a7fe9414d6d98f1f7e8b3a9b2d3b9714d6636/bin/scalafmt -------------------------------------------------------------------------------- /build.sbt: -------------------------------------------------------------------------------- 1 | def scalameta = "4.2.3" 2 | def scalafix = "0.9.7" 3 | def scala212 = "2.12.10" 4 | 5 | inThisBuild( 6 | List( 7 | organization := "org.scalameta", 8 | scalaVersion := scala212, 9 | libraryDependencies ++= Seq( 10 | "org.scalatest" %% "scalatest" % "3.0.5" % Test 11 | ), 12 | resolvers += Resolver.sonatypeRepo("releases") 13 | ) 14 | ) 15 | 16 | name := "scalameta-tutorial" 17 | skip in publish := true 18 | 19 | lazy val docs = project 20 | .in(file("scalameta-docs")) 21 | .settings( 22 | buildInfoKeys := Seq[BuildInfoKey]( 23 | "scalameta" -> scalameta 24 | ), 25 | buildInfoPackage := "docs", 26 | moduleName := "scalameta-docs", 27 | mdoc := run.in(Compile).evaluated, 28 | libraryDependencies ++= List( 29 | "org.scalameta" %% "testkit" % scalameta, 30 | "ch.epfl.scala" %% "scalafix-core" % scalafix 31 | ) 32 | ) 33 | .enablePlugins(BuildInfoPlugin, DocusaurusPlugin) 34 | -------------------------------------------------------------------------------- /docs-out/assets/astexplorer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/scalameta/tutorial/789a7fe9414d6d98f1f7e8b3a9b2d3b9714d6636/docs-out/assets/astexplorer.png -------------------------------------------------------------------------------- /docs-out/assets/established.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/scalameta/tutorial/789a7fe9414d6d98f1f7e8b3a9b2d3b9714d6636/docs-out/assets/established.png -------------------------------------------------------------------------------- /docs-out/assets/foobar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/scalameta/tutorial/789a7fe9414d6d98f1f7e8b3a9b2d3b9714d6636/docs-out/assets/foobar.png -------------------------------------------------------------------------------- /docs-out/assets/foobar.png.gz: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/scalameta/tutorial/789a7fe9414d6d98f1f7e8b3a9b2d3b9714d6636/docs-out/assets/foobar.png.gz -------------------------------------------------------------------------------- /docs-out/assets/semantic-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/scalameta/tutorial/789a7fe9414d6d98f1f7e8b3a9b2d3b9714d6636/docs-out/assets/semantic-api.png -------------------------------------------------------------------------------- /docs-out/assets/syntactic-api.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/scalameta/tutorial/789a7fe9414d6d98f1f7e8b3a9b2d3b9714d6636/docs-out/assets/syntactic-api.png -------------------------------------------------------------------------------- /docs-out/assets/tree.svg: -------------------------------------------------------------------------------- 1 | 2 | 4 | 6 | 7 | 9 | 10 | Router 11 | 12 | 13 | Name1 14 | 15 | Name 16 | 17 | 18 | Name2 19 | 20 | Name 21 | 22 | 23 | Type1 24 | 25 | Type 26 | 27 | 28 | Type1->Name1 29 | 30 | 31 | 32 | 33 | Tuple1 34 | 35 | Tuple 36 | 37 | 38 | Type1->Tuple1 39 | 40 | 41 | 42 | 43 | Function 44 | 45 | Function 46 | 47 | 48 | Type1->Function 49 | 50 | 51 | 52 | 53 | Type2 54 | 55 | Type 56 | 57 | 58 | Tuple2 59 | 60 | Tuple 61 | 62 | 63 | Term 64 | 65 | Term 66 | 67 | 68 | Term->Name2 69 | 70 | 71 | 72 | 73 | Term->Tuple2 74 | 75 | 76 | 77 | 78 | Block 79 | 80 | Block 81 | 82 | 83 | Term->Block 84 | 85 | 86 | 87 | 88 | For 89 | 90 | For 91 | 92 | 93 | Term->For 94 | 95 | 96 | 97 | 98 | While 99 | 100 | While 101 | 102 | 103 | Term->While 104 | 105 | 106 | 107 | 108 | If 109 | 110 | If 111 | 112 | 113 | Term->If 114 | 115 | 116 | 117 | 118 | Match 119 | 120 | Match 121 | 122 | 123 | Term->Match 124 | 125 | 126 | 127 | 128 | Apply 129 | 130 | Apply 131 | 132 | 133 | Term->Apply 134 | 135 | 136 | 137 | 138 | InfixApply 139 | 140 | InfixApply 141 | 142 | 143 | Term->InfixApply 144 | 145 | 146 | 147 | 148 | Defn 149 | 150 | Defn 151 | 152 | 153 | Defn->Type2 154 | 155 | 156 | 157 | 158 | Class 159 | 160 | Class 161 | 162 | 163 | Defn->Class 164 | 165 | 166 | 167 | 168 | Trait 169 | 170 | Trait 171 | 172 | 173 | Defn->Trait 174 | 175 | 176 | 177 | 178 | Object 179 | 180 | Object 181 | 182 | 183 | Defn->Object 184 | 185 | 186 | 187 | 188 | Val 189 | 190 | Val 191 | 192 | 193 | Defn->Val 194 | 195 | 196 | 197 | 198 | Def 199 | 200 | Def 201 | 202 | 203 | Defn->Def 204 | 205 | 206 | 207 | 208 | Decl 209 | 210 | Decl 211 | 212 | 213 | Decl->Type2 214 | 215 | 216 | 217 | 218 | Decl->Val 219 | 220 | 221 | 222 | 223 | Decl->Def 224 | 225 | 226 | 227 | 228 | Template 229 | 230 | Template 231 | 232 | 233 | Import 234 | 235 | Import 236 | 237 | 238 | Mod 239 | 240 | Mod 241 | 242 | 243 | Final 244 | 245 | Final 246 | 247 | 248 | Mod->Final 249 | 250 | 251 | 252 | 253 | Lazy 254 | 255 | Lazy 256 | 257 | 258 | Mod->Lazy 259 | 260 | 261 | 262 | 263 | Sealed 264 | 265 | Sealed 266 | 267 | 268 | Mod->Sealed 269 | 270 | 271 | 272 | 273 | Tree 274 | 275 | Tree 276 | 277 | 278 | Tree->Type1 279 | 280 | 281 | 282 | 283 | Tree->Template 284 | 285 | 286 | 287 | 288 | Tree->Mod 289 | 290 | 291 | 292 | 293 | Stat 294 | 295 | Stat 296 | 297 | 298 | Tree->Stat 299 | 300 | 301 | 302 | 303 | Stat->Term 304 | 305 | 306 | 307 | 308 | Stat->Defn 309 | 310 | 311 | 312 | 313 | Stat->Decl 314 | 315 | 316 | 317 | 318 | Stat->Import 319 | 320 | 321 | 322 | 323 | 324 | -------------------------------------------------------------------------------- /docs-out/example.scala: -------------------------------------------------------------------------------- 1 | object Example extends App { println("Hello from a file!") } 2 | -------------------------------------------------------------------------------- /docs-out/misc/built-with-scalameta.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: built-with-scalameta 3 | title: Built with Scalameta 4 | --- 5 | 6 | Feel free to add your project to this list by submitting a pull request 7 | [here](https://github.com/scalameta/tutorial/blob/master/docs/misc/built-with-scalameta.md). 8 | 9 | - [Scalafmt](https://scalameta.org/scalafmt): code formatter. 10 | - [Scalafix](https://scalacenter.github.io/scalafix/): refactoring and linting 11 | tool. 12 | - [Metals](https://scalameta.org/metals/): Language Server Protocol 13 | implementation. 14 | - [Metabrowse](https://scalameta.org/metabrowse): static site generator to browse 15 | source code with "Jump to definition" and "Find references". 16 | - [Stags](https://github.com/pjrt/stags): Scala tags generator. 17 | - [AST explorer](https://astexplorer.net/#/gist/ec56167ffafb20cbd8d68f24a37043a9/74efb238ad02abaa8fa69fc80342563efa8a1bdc): 18 | interactive explorer of Scala syntax trees. 19 | - [Metarpheus](https://github.com/buildo/metarpheus): 20 | extract models and apis from a spray-based server. 21 | - [sbt-ammonite-classpath](https://github.com/ThoughtWorksInc/sbt-ammonite-classpath): an sbt plug-in to export classpath of an sbt project to Ammonite Script, which can be then used in Ammonite REPL or Jupyter Scala. 22 | - [sbt-example](https://github.com/ThoughtWorksInc/sbt-example): an sbt plug-in 23 | for creating unit tests from Scaladoc. 24 | - [sbt-doctest](https://github.com/tkawachi/sbt-doctest/): generates tests from 25 | examples in Scaladoc. 26 | - [Stryker4s](https://github.com/stryker-mutator/stryker4s): Test your tests with mutation testing. 27 | 28 | -------------------------------------------------------------------------------- /docs-out/misc/presentations.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: presentations 3 | title: Presentations 4 | --- 5 | 6 | ## How We Built Tools That Scale to Millions of Lines of Code (ScalaDays New York 2018) 7 | 8 | This talk outlines the work that we did at Twitter to add semantic functionality 9 | to code browsing, code review and code evolution tools. We use SemanticDB - an 10 | opensource data model for semantic information developed in Scalameta. We have 11 | implemented experimental improvements to the Twitter development workflow, 12 | integrating opensource and closed-source solutions. 13 | 14 | - Video: 15 | https://na.scaladays.org/schedule/how-we-built-tools-that-scale-to-millions-of-lines-of-code 16 | - Slides: 17 | http://scalameta.org/talks/2018-06-20-HowWeBuiltToolsThatScaleToMillionsOfLoc.pdf 18 | 19 | ## Six Steps from Zero to IDE (flatMap(Oslo) and ScalaDays Berlin 2018) 20 | 21 | This talk is about the Language Server Protocol and Metals, a language server 22 | for Scala that we are building with SemanticDB. The talk explains the 23 | architecture of Metals and what components are needed to build a good 24 | interactive editing experience for Scala. 25 | 26 | - Video: https://slideslive.com/38908105/six-steps-from-zero-to-ide 27 | - Slides: https://geirsson.com/assets/flatmap-2018.pdf 28 | 29 | ## SemanticDB for Scala developer tools (ScalaSphere Krakow 2018) 30 | 31 | This talk covers what SemanticDB is and how it enables a new way to build 32 | developer tools for Scala. We show how SemanticDB data looks like, explain how 33 | to use the utilities metac, metacp, mtags and mtags to produce and read 34 | SemanticDB, and how applications like Scalafix, Metabrowse and Metals are using 35 | SemanticDB today. 36 | 37 | - Video: https://youtu.be/1p_sYlgs7Lg 38 | - Slides: https://geirsson.com/assets/scalasphere-2018.pdf 39 | 40 | ## Semantic Tooling at Twitter (ScalaDays Copenhagen 2017) 41 | 42 | This talk introduces semantic databases, the cornerstone of the Scalameta 43 | semantic API, and explains how semantic databases can be used to integrate with 44 | Kythe, a language-agnostic ecosystem for developer tools. In this talk, we 45 | presented our vision of next-generation semantic tooling for the Scala 46 | ecosystem. 47 | 48 | - Video: https://www.youtube.com/watch?v=4yqDFsdKciA 49 | - Slides: http://scalameta.org/talks/2017-06-01-SemanticToolingAtTwitter.pdf 50 | 51 | ## Metaprogramming 2.0 (ScalaDays Berlin 2016) 52 | 53 | This talk explains the status of Scalameta, demonstrates key features, presents 54 | the early adopters and publishes our plans for the future. The centerpiece of 55 | the talk is the demo of a new macro system for Scala, which is no longer part of 56 | Scalameta. Nonetheless, the talk still does a good job of showcasing potential 57 | usecases for Scalameta and highlighting contributions from our amazing 58 | community. 59 | 60 | - Video: https://www.youtube.com/watch?v=IPnd_SZJ1nM 61 | - Slides: http://scalamacros.org/paperstalks/2016-06-17-Metaprogramming20.pdf 62 | 63 | -------------------------------------------------------------------------------- /docs-out/semanticdb/guide.md: -------------------------------------------------------------------------------- 1 | --- 2 | id: guide 3 | title: SemanticDB Guide 4 | sidebar_label: Guide 5 | --- 6 | 7 | 8 | SemanticDB is a data model for semantic information such as symbols and types 9 | about programs in Scala and other languages. SemanticDB decouples production and 10 | consumption of semantic information, establishing documented means for 11 | communication between tools. 12 | 13 | In this document, we introduce practical aspects of working with SemanticDB. We 14 | describe the tools that can be used to produce SemanticDB payloads, the tools 15 | can be used to consume SemanticDB payloads and useful tips & tricks for working 16 | with SemanticDB. If you're looking for a comprehensive reference of SemanticDB 17 | features, check out [the specification](specification.html). 18 | 19 | 20 | 21 | ## Installation 22 | 23 | This guide covers several non-standard command-line tools: `metac` and 24 | `metap`. To install these tools on your computer, you can do the following: 25 | 26 | - Install the `coursier` command-line tool by following the 27 | [instructions here](https://github.com/coursier/coursier/#command-line). 28 | Make sure you are using the latest coursier version (1.1.0-M6 or newer). 29 | ```bash 30 | curl -Lo coursier https://git.io/coursier-cli && chmod +x coursier 31 | ``` 32 | - Add the following aliases to your shell: 33 | 34 | [![Maven Central](https://maven-badges.herokuapp.com/maven-central/org.scalameta/scalameta_2.12/badge.svg)](https://maven-badges.herokuapp.com/maven-central/org.scalameta/scalameta_2.12) 35 | 36 | ```bash 37 | alias metac="coursier launch org.scalameta:metac_2.12.8:4.1.9 -- -cp $(coursier fetch -p org.scala-lang:scala-library:2.12.8)" 38 | alias metap="coursier launch -M scala.meta.cli.Metap org.scalameta:scalameta_2.11:4.1.9 --" 39 | ``` 40 | NOTE. These installation instructions are for the current unstable `master` branch, 41 | it's recommended to view this document at the latest git tag instead of `master`. 42 | 43 | (Optional) Instead of running `metap` on the JVM, you can build a native binary 44 | on macOS or Linux. Thanks to [Scala Native](https://scala-native.readthedocs.io/en/latest/), 45 | native Metap works much faster than regular Metap (on a personal laptop of 46 | one of the authors of this guide, a simple Metap invocation takes 500+ ms on JVM 47 | and 10 ms on native). 48 | 49 | 1. Install the [`coursier`](https://github.com/coursier/coursier/#command-line-1) command-line 50 | version 1.1.0-M6 or later. 51 | 1. Setup the [development environment for Scala Native](http://www.scala-native.org/en/latest/user/setup.html#installing-clang-and-runtime-dependencies). 52 | 1. Link a native `metap` binary. 53 | 54 | ```bash 55 | coursier bootstrap org.scalameta:metap_native0.3_2.11:4.1.0 -o metap -f --native --main scala.meta.cli.Metap 56 | ``` 57 | 58 | ## Example 59 | 60 | Let's generate SemanticDB for a simple Scala program. (At the moment, 61 | our SemanticDB producers provide full Scala support and partial Java support. 62 | Theoretically, [the SemanticDB protobuf schema](https://github.com/scalameta/scalameta/blob/master/semanticdb/semanticdb/semanticdb.proto) 63 | can accommodate other languages as well, but we haven't attempted to do that yet). 64 | 65 | ```scala 66 | object Test { 67 | def main(args: Array[String]): Unit = { 68 | println("hello world") 69 | } 70 | } 71 | ``` 72 | 73 | In order to obtain a SemanticDB corresponding to this program, let's use 74 | the Metac command-line tool. For more information on other tools that can 75 | produce SemanticDB, [see below](#producing-semanticdb). 76 | 77 | ``` 78 | $ metac Test.scala 79 | ``` 80 | 81 | `metac` is a thin wrapper over the Scala compiler. It supports the same 82 | command-line arguments as `scalac` supports, but instead of generating .class 83 | files it generates .semanticdb files. Newer versions of Metac may also generate 84 | an accompanying .semanticidx file, but it's an experimental feature, so we won't 85 | be discussing it in this document. 86 | 87 | ``` 88 | $ tree 89 | . 90 | ├── META-INF 91 | │   └── semanticdb 92 | │   └── Test.scala.semanticdb 93 | └── Test.scala 94 | ``` 95 | 96 | If we take a look inside Test.scala.semanticdb, we'll see a weird mix of 97 | legible-looking text and special characters. That's because .semanticdb 98 | files store protobuf payloads. 99 | 100 | ``` 101 | $ xxd META-INF/semanticdb/Test.scala.semanticdb 102 | 00000000: 0aaa 0408 0412 0a54 6573 742e 7363 616c .......Test.scal 103 | 00000010: 612a 580a 1a5f 656d 7074 795f 2f54 6573 a*X.._empty_/Tes 104 | 00000020: 742e 6d61 696e 2829 2e28 6172 6773 2918 t.main().(args). 105 | 00000030: 082a 0461 7267 7380 0101 8a01 2e22 2c0a .*.args......",. 106 | 00000040: 2a12 2812 0c73 6361 6c61 2f41 7272 6179 *.(..scala/Array 107 | 00000050: 231a 1812 1612 1473 6361 6c61 2f50 7265 #......scala/Pre 108 | 00000060: 6465 662e 5374 7269 6e67 232a 530a 0d5f def.String#*S.._ 109 | 00000070: 656d 7074 795f 2f54 6573 742e 180a 2008 empty_/Test... . 110 | 00000080: 2a04 5465 7374 8001 018a 012f 0a2d 0a00 *.Test...../.-.. 111 | 00000090: 1211 120f 120d 7363 616c 612f 416e 7952 ......scala/AnyR 112 | 000000a0: 6566 2322 160a 145f 656d 7074 795f 2f54 ef#"..._empty_/T 113 | 000000b0: 6573 742e 6d61 696e 2829 2e92 0102 3a00 est.main()....:. 114 | 000000c0: 2a5c 0a14 5f65 6d70 7479 5f2f 5465 7374 *\.._empty_/Test 115 | ... 116 | ``` 117 | 118 | In order to make sense of .semanticdb files, we can use the Metap 119 | command-line tool. For more information on other tools that can 120 | consume SemanticDB, [see below](#consuming-semanticdb). 121 | 122 | ``` 123 | $ metap . 124 | Test.scala 125 | ---------- 126 | 127 | Summary: 128 | Schema => SemanticDB v4 129 | Uri => Test.scala 130 | Text => empty 131 | Language => Scala 132 | Symbols => 3 entries 133 | Occurrences => 7 entries 134 | 135 | Symbols: 136 | _empty_/Test. => final object Test extends AnyRef { +1 decls } 137 | _empty_/Test.main(). => method main(args: Array[String]): Unit 138 | _empty_/Test.main().(args) => param args: Array[String] 139 | 140 | Occurrences: 141 | [0:7..0:11) <= _empty_/Test. 142 | [1:6..1:10) <= _empty_/Test.main(). 143 | [1:11..1:15) <= _empty_/Test.main().(args) 144 | [1:17..1:22) => scala/Array# 145 | [1:23..1:29) => scala/Predef.String# 146 | [1:33..1:37) => scala/Unit# 147 | [2:4..2:11) => scala/Predef.println(+1). 148 | ``` 149 | 150 | Metap prettyprints various parts of the SemanticDB payload in correspondence 151 | with [the SemanticDB specification](specification.html). Here are the most 152 | important parts: 153 | * `Uri` stores the URI of the source file relative to 154 | the directory where the SemanticDB producer was invoked. 155 | * `Symbols` contains information about definitions in the source 156 | file, including modifiers, signatures, etc. 157 | 158 | For example, `_empty_/Test.main(). => method main: (args: Array[String]): Unit` 159 | says that `main` is a method with one parameter of type `Array[String]`. 160 | * `Occurrences` contains a list of identifiers from the source file with 161 | their line/column-based positions and unique identifiers pointing to 162 | corresponding definitions resolved by the compiler. 163 | 164 | For example, `[2:4..2:11): println => scala/Predef.println(+1).` says that 165 | the identifier `println` on line 3 (zero-based numbering scheme!) refers 166 | to the second overload of `println` from `scala/Predef`. 167 | 168 | ## What is SemanticDB good for? 169 | 170 | SemanticDB decouples producers and consumers of semantic information about 171 | programs and establishes [a rigorous specification](specification.html) of the 172 | interchange format. 173 | 174 | Thanks to that, SemanticDB-based tools like [Scalafix](#scalafix), 175 | [Metadoc](#metadoc) and [Metals](#metals) don't need to know about compiler 176 | internals and can work with any compiler that supports SemanticDB. 177 | This demonstrably improves developer experience, portability and scalability. 178 | Next-generation semantic tools at Twitter are based on SemanticDB. 179 | 180 | For more information about the SemanticDB vision, check out our talks: 181 | * [Semantic Tooling at Twitter](https://www.youtube.com/watch?v=4yqDFsdKciA) 182 | (June 2017) by Eugene Burmako & Stu Hood. 183 | * [SemanticDB for Scala developer tools](https://t.co/Z080F6JxyQ?amp=1) 184 | (April 2018) by Ólafur Páll Geirsson. 185 | * [How We Built Tools That Scale to Millions of Lines of Code](https://na.scaladays.org/schedule/how-we-built-tools-that-scale-to-millions-of-lines-of-code) 186 | (June 2018) by Eugene Burmako. 187 | 188 | ## Producing SemanticDB 189 | 190 | ### Scalac compiler plugin 191 | 192 | The `semanticdb-scalac` compiler plugin injects itself immediately after the 193 | `typer` phase of the Scala compiler and then harvests and dumps semantic 194 | information from Scalac in SemanticDB format. 195 | 196 | ``` 197 | scalac -Xplugin:path/to.jar -Yrangepos [ ...] [ ...] [ ...] 198 | ``` 199 | 200 | The compiler plugin supports the following options that can 201 | be passed through Scalac in the form of `-P:semanticdb: