Project configuration explained

Although the work on new Scala project configuration is still in progress, here's a brief clarification.

  • A module that requires compiling with Scalac should have a Scala facet attached.
  • Facet refers to "Compiler library" which is used to instantiate Scalac inside JVM (the library provides "compiler classpath" that is completely separated from "project classpath")
    Compiler library (usually) should include scala-compiler*.jar and scala-library*.jar.
    For special purposes, compiler library may include directories (like "/build/classes/", etc), in that case, no library validation is performed.
  • Facet holds custom compiler options and a list of Scalac plugins (relative paths allowed).
  • As usual, modules that use Scala standard library should include it in module dependencies.
  • Both compiler library and standard library may be created using build-in wizard (from Scala distribution).
  • Plugins doesn't include bundled Scalac anymore.
  • Maven projects can be imported automatically.


Mini HOWTOs:

To create a new project that uses Scala:

  1. In "New Project" wizard check "Scala" in technologies list.
  2. Provide a path to Scala installation (if not detected)


To add a new module that uses Scala into existing project:

  1. In "Add Module" wizard check "Scala" in technologies list.
  2. Provide a path to Scala installation (if not detected)


To add Scala support to existing module:

  1. Right-click the module in Project View, choose "Add Framework Support..."
  2. Check "Scala" in technologies list (unavailable if module has Scala facet attached)
  3. Provide a path to Scala installation (if not detected)


To manually configure existing module:

  1. Create library "scala-compiler":
      • Classes:
        • scala-compiler.jar
        • scala-library.jar
    • Create library "scala-library":
      • Classes:
        • scala-dbc.jar
        • scala-library.jar
        • scala-swing.jar
      • Sources:
          • scala-dbc-src.jar
          • library-src.jar
          • swing-src.jar
        • Docs:
          • /doc/scala-devel-docs/api/
          (if you downloaded Scala as an archive, you need to get separate API docs archive and extract it so that <scala home>\doc\scala-devel-docs\api exist; if you installed Scala using LzPack, then API docs are already there)
      • Add Scala facet to the module, select "scala-compiler" library as compiler library
      • Add "scala-library" to module dependencies.


      Hints:

      • Don't add Scala compiler library to module dependencies (unless you really need Scala compiler classes in your code)
      • Remember to attach "scala-library*.jar" to Scala compiler library, it's a dependency of "scala-compiler*.jar" itself.


      Comments and suggestions welcome.


      Screenshots

      Scala support for existing module:
      framework.png

      Wizard (on new project, on new module, after "Add Framework Support..."):
      support.png

      Libraries:
      libraries.png

      Standard library:
      standard.png

      Compiler library:
      compiler.png

      Module dependencies:
      dependencies.png

      Facet settings:
      facet.png

      Advanced facet settings:
      settings.png

      Autocompletion (Scala standard library):
      completion.png

      Documentation lookup (Scala standard library API docs):
      docs.png

      Definition lookup (Scala standard library sources):
      implementation.png

      22 comments

      Hi Pavel,

      many thanks, the new facet configuration is much more intuitive and user-friendly. I only have the following issue when using it for the scala compiler:

      The facet configuration only accepts libraries which contain a "scala-compiler*.jar". Providing a library that contains a classfile directory ("build/locker/classes/compiler") does not work. The same is probably true for "scala-library*.jar". For the compiler module, i'd like to link a library which contains ("build/locker/classes/compiler", "build/locker/classes/library", "lib/fjbg.jar", "lib/msil.jar").

      Thanks: Lukas

      0

      There's a dilemma here:

      • normal users want configuration to be simple (zero-configuration is an ideal one); most setting are predictable and uniform, thus we can catch and report all "errors"
      • advanced users desire complete control over all parameters; settings may be uncommon, any validation is a priori restriction.


      However, we want IDEA to be able to build Scala project, so I'm going to reduce the validation of "compiler library" (check the next nightly build).

      0

      i understand.. it could be a warning in the facet configuration, but not an error when trying to compile.
      many thanks: lukas

      0

      I disabled all warnings for libraries with directory entries (like "build/locker/classes/compiler").

      Please, let me know if there are any other compilation problems.

      0

      What needs to be done for existing maven projects. I just jumped versions from the no-facets to the new facets. Before the scala compiler was picked up via the maven dependency. Now it is not. Force Reimport has no effect.

      Will I now have to manually manage/sync the compiler version specified in maven with the facet?

      Hmm, actually now I'm getting corruption. See attached screen shot. No errors in the log and not thread dumps. I'm wondering if this corruption is maven related. Its similar to SCL-2088).

      -barry



      Attachment(s):
      ScreenHunter_01 Aug. 06 09.44.gif
      0

      All Maven dependencies should be handled automatically.

      "Corruption" looks like some bug with character encoding, that is hardly related to Scala plugin itself.

      SCL-2088 assigne changed, I hope the issue will be fixed soon.

      0

      I have a single-module project that contains the following Maven dependencies:


      ...
              <dependency>
                  <groupId>org.scala-lang</groupId>
                  <artifactId>scala-library</artifactId>
                  <version>2.8.0</version>
              </dependency>

              <dependency>
                  <groupId>org.scala-lang</groupId>
                  <artifactId>scala-compiler</artifactId>
                  <version>2.8.0</version>
                  <scope>compile</scope>
              </dependency>
      ...


      When I attempt to run a Scala object main method from this module, I get the nice message box "Please, adjust compiler library in Scala facet: no scala-library*.jar found".
      The facet configuration allows me to pick a compiler library only. Where in the facet config am I supposed to configure a library library?

      More to the point, since all the required elements are already in my Maven pom.xml, why am I forced to mess with facet settings and such?

      -tt (using plugin version #0.3.1979)

      0

      How do I run the wizard that creates the Scala Compiler library?

      0

      Dependency is a claim that your code wants to use classes from a library, it have nothing to do with compilation.

      So, the following declaration adds Scala compiler classes to your project classpath:

      <!-- Usually, that's not needed unless you directly use compiler classes in your code -->
      <dependency>

      <groupId>org.scala-lang</groupId>
           <artifactId>scala-compiler</artifactId>
           <version>2.8.0</version>
           <scope>compile</scope>
      </dependency>


      This is how Scala compiler inside pom.xml should be specified:


      <!-- Inside "build / plugins" element -->

      <plugin>
           <groupId>org.scala-tools</groupId>
           <artifactId>maven-scala-plugin</artifactId>
           <executions>
                <execution>
                     <goals>
                          <goal>compile</goal>
                          <goal>testCompile</goal>
                     </goals>
                </execution>
           </executions>
           <configuration>
                <scalaVersion>${scala.version}</scalaVersion>
                <args>
                     <arg>-target:jvm-1.5</arg>
                </args>
           </configuration>
      </plugin>


      That declaration has "compile" goal to run when you enter "mvn compile".
      Scala compiler library is discovered implicitly, by maven-scala-plugin using scalaVersion property.




      Such declaration should be automatically imported by IDEA as a Scala compiler library for facet.
      (regular dependencies, like scala-library, should be imported as well - as entries in module dependencies list).


      P.S. previous versions of the plugin considered "scala-compiler" dependency as a Scala compiler, that was a misbehavior.
      0

      There's "all-or-none" wizard only.

      Either delete a facet from a module and run "Add framework support..." wizard, or manually create a library with "scala-compiler.jar" and "scala-library.jar" attached.

      0

      If I reimport the modules from Maven, it creates per module an empty library named 'maven: org.scala-lang:scala-compiler:2.8.0.RC6'. Since it is empty, I get errors that no scala-library*.jar . Because import happens automatically, even if I configure my own 'Scala SDK' global library and attach it to all modules (one by one, a long and slow process), it is detached and the empty library is set instead.

      0

      Looks like a bug, I've created an issue.

      0

      Why must there be a configuration per module? Isn't it easier to have to set it once in the general settings and override per-need in the module?

      0

      It's because all Scala support may be configured as project-local, but general settings are system-wide.
      After all, setting inheritance is some kind of overkill, because nobody usually touches them anyway.

      0

      how do i set project-local settings for scala? (i tread the scala facets as module-local)

      0

      > i tread the scala facets as module-local)
      By "project-local" I mean that configuration doesn't depend on system-wide IDEA settings.

      > how do i set project-local settings for scala?
      (to a point):

      • you can create project-level "scala-library" and attach it to dependencies (for all modules).
      • you can reate project-level "scala-compiler" library and choose it as a compiler in all modules.
      • no parts of project configuration depend on global IDEA settings (like SDKs, compilers, etc)


      Most users want to explicitly specify that module should be compiled by Scalac, so facet is used as "marker" for Scala compiler usage.
      Choosing compiler library in facet does not seem to be a heavy burden.

      0

      if i do this,how do i prevent the setting in the scala facet from taking precedence?

      0

      Global Scala compiler settings will be removed soon.
      Several places for the compiler settings is an excessive complication. The same is true for inheritance of global (system-wide) settings by module-local settings (that may lead to unexpected behavior on different systems).

      I admit that current way of configuring project may require to duplicate some settings (like compiler options or compiler plugins) for each module, but it seems that in most cases that will cause less troubles than dealing with setting inheritance and overriding.

      0

      If I attached the javadoc, should I see text descriptions for various scala builtin when I use completion (ctrl-space)?
      Not seeing it currently and would like to.

      Build 1814 is an improvement. Thank you.

      0

      > Not seeing it currently and would like to.
      Docs (and sources) should work just like in Java: select symbol (or press Ctrl + Space), then press Ctrl + Q (docs) or Ctrl + Shift + I (implementation).

      If you downloaded Scala as an archive, you need to additionaly download API docs archive and extract it so that <scala home>\doc\scala-devel-docs\api exist.
      (if you installed Scala using LzPack installer, then API docs are already there).

      Ensure that module dependencies include Scala standard library library with <scala home>\doc\scala-devel-docs\api attached.

      > Build 1814 is an improvement

      I recommend you to try nightly builds, usually, nightly builds are quite stable and include many new features and bugfixes.

      0

      Pilot error on my part. Works fine, thanks.

      0

      Please sign in to leave a comment.