[0.9]Adrift in a sea of types

[Rodrigo Cano]

I'm trying to migrate my plugins from sbt 0.7 to 0.9 and find myself completely lost as where to start. I've read most of the pages in github, several times, I tried reading the source code from some tasks helping myself with the scaladocs but still, I cannot get the picture . I would rather not read thousands of lines of sourcecode to understand how it works :S

For example, there is no mention of what an Initialized is, to make things worst, it is not even listed in the scaladocs!. Also, things are all the time implicitly converted to who knows what, I couldn't find those implcits, so I don't know when something is going to be converted or not. I tried looking for the definition of methods like :=, ~=, etc, but as I found later looking at the sources, they are in some RicherClasses that are not listed in the scaladocs again.

I want to write some InputTasks but there is no explicit documentation of how to get that done, just that they are similar to Commands, but they don't even seem to come from the same hierarchy, I've been trying for 3 days now with no success, so excuse the frustrated tone. 

I very welcome any advice. Thanks.

[Mark Harrah]

On Wed, 25 May 2011 16:43:01 -0300
Rodrigo Cano <ioni...@gmail.com> wrote:

> I'm trying to migrate my plugins from sbt 0.7 to 0.9 and find myself
> completely lost as where to start. I've read most of the pages in github,
> several times, I tried reading the source code from some tasks helping
> myself with the scaladocs but still, I cannot get the picture . I would
> rather not read thousands of lines of sourcecode to understand how it works
> :S

It might be more helpful to read the hyperlinked version and Defaults is a good place to start:

http://harrah.github.com/xsbt/latest/sxr/Defaults.scala.html

All of the built in settings are defined there. The keys are in Keys:

http://harrah.github.com/xsbt/latest/sxr/Keys.scala.html

> For example, there is no mention of what an Initialized is, to make things
> worst, it is not even listed in the scaladocs!.

It is nested, so it isn't in the top-level list:

http://harrah.github.com/xsbt/latest/api/sbt/Init$Initialize.html

> Also, things are all the
> time implicitly converted to who knows what, I couldn't find those implcits,
> so I don't know when something is going to be converted or not. I tried
> looking for the definition of methods like :=, ~=, etc, but as I found later
> looking at the sources, they are in some RicherClasses that are not listed
> in the scaladocs again.

Most of these are in Scoped, which is in Structure.scala:

http://harrah.github.com/xsbt/latest/api/sbt/Scoped$.html

http://harrah.github.com/xsbt/latest/sxr/Structure.scala.html

> I want to write some InputTasks but there is no explicit documentation of
> how to get that done, just that they are similar to Commands, but they don't
> even seem to come from the same hierarchy, I've been trying for 3 days now
> with no success, so excuse the frustrated tone.

The equivalent to 0.7.x method tasks is:

inputTask { (argsTask: TaskKey[Seq[String]]) =>
(argsTask, ... other inputs ...) map { (args: Seq[String], ...) =>
<task implementation here>
}
}

For example:

val hello = InputKey[Unit]("hello")

hello <<= inputTask { argsT =>
(argsT, scalaVersion, sbtVersion) map { (args, scv, sbv)
println("Scala version: " + scv)
println("sbt version: " + sbv)
println("Args: " + args.mkString(" "))
}
}

> I very welcome any advice. Thanks.

I have tried to be fairly responsive to questions related to 0.9.x. Definitely don't wait three days before asking!

-Mark

[Rodrigo Cano]

It might be more helpful to read the hyperlinked version and Defaults is a good place to start:

http://harrah.github.com/xsbt/latest/sxr/Defaults.scala.html

All of the built in settings are defined there.  The keys are in Keys:

http://harrah.github.com/xsbt/latest/sxr/Keys.scala.html

I tried reading Defaults.scala, using runMainTask as a reference, but I cant fully understand the code, because there are many implicit conversions I don't understand on which circumstances apply, so I couldn't extract much from It. Keys OTOH is fairly simple and useful.

Maybe some documentation on Initialize and the implicit conversion would be useful for plugin writers, at least they would be for me. I could understand the code of 0.7 very well, but 0.9 really dizzies me with all the maps and conversions. For example (from Basic Configuration)

// Use the name and version to define the jar name.
jarName <<= (name, version) {
	(name: String, version: String) => name + "-" + version + ".jar"
}

the method <<= takes an Initialize (I think, or an App?, couldn't find jarName in Keys), but here we are creating a tuple, and then an apply? so I think there is some implicit happening there, would it work with Seq(name, version) {...} ?, I mean, I don't know what will and what won't be converted... I might as well be complicating myself with unnecessary concerns?

When you write "(name, version) map something", I presume a key is being created from the tuple, is that right? is this conversion the same happening in the jarName example?

The equivalent to 0.7.x method tasks is:

inputTask { (argsTask: TaskKey[Seq[String]]) =>

 (argsTask, ... other inputs ...) map { (args: Seq[String], ...) =>

  <task implementation here>

 }

}

For example:

val hello = InputKey[Unit]("hello")

hello <<= inputTask { argsT =>

 (argsT, scalaVersion, sbtVersion) map { (args, scv, sbv)

   println("Scala version: " + scv)

   println("sbt version: " + sbv)

   println("Args: " + args.mkString(" "))

 }

}

Thanks, this is really useful.

I have tried to be fairly responsive to questions related to 0.9.x.  Definitely don't wait three days before asking!

As people seems to not be having problems, I thought it would probably be me missing something, so I tried to exhaust my cognitive skills before bothering, I don't like to ask things that are clearly defined in the manual.

Thanks for the reply.

--
You received this message because you are subscribed to the Google Groups "simple-build-tool" group.
To post to this group, send email to simple-b...@googlegroups.com.
To unsubscribe from this group, send email to simple-build-t...@googlegroups.com.
For more options, visit this group at http://groups.google.com/group/simple-build-tool?hl=en.

[Mark Harrah]

On Wed, 25 May 2011 18:42:32 -0300
Rodrigo Cano <ioni...@gmail.com> wrote:
> > It might be more helpful to read the hyperlinked version and Defaults is a
> > good place to start:
>
> > http://harrah.github.com/xsbt/latest/sxr/Defaults.scala.html
>
> > All of the built in settings are defined there. The keys are in Keys:
>
> > http://harrah.github.com/xsbt/latest/sxr/Keys.scala.html
>
>
> I tried reading Defaults.scala, using runMainTask as a reference, but I cant
> fully understand the code, because there are many implicit conversions I
> don't understand on which circumstances apply, so I couldn't extract much
> from It. Keys OTOH is fairly simple and useful.

The built-in input tasks like run-main and test-only are about as complex as it gets, so I can imagine that was a bit of a rough starting point. In theory the sxr docs would help out with implicit conversions, but I see that the locations are messed up for <<= and :=. Ideally you'd be able to click through to at least see where the method is defined.

Structure.scala contains all of the relevant implicits I think, although I don't know how easy it is to absorb them.

> Maybe some documentation on Initialize and the implicit conversion would be
> useful for plugin writers, at least they would be for me. I could understand
> the code of 0.7 very well, but 0.9 really dizzies me with all the maps and
> conversions. For example (from Basic Configuration)
>

> // Use the name and version to define the jar name.jarName <<= (name, version) {

> (name: String, version: String) => name + "-" + version + ".jar"}
>
> the method <<= takes an Initialize (I think, or an App?, couldn't find
> jarName in Keys), but here we are creating a tuple, and then an apply? so I
> think there is some implicit happening there, would it work with Seq(name,
> version) {...} ?, I mean, I don't know what will and what won't be
> converted... I might as well be complicating myself with unnecessary
> concerns?
>
> When you write "(name, version) map something", I presume a key is being
> created from the tuple, is that right? is this conversion the same happening
> in the jarName example?
>

jarName no longer exists and that documentation apparently wasn't updated. I will have to come up with a new example. Initialize is certainly interesting, but I'm not sure how much you need to know about it other than what requires it and what produces it.

<<= does take an Initialize. The App I assume you are talking about is an alias for Initialize[Task[T]]. The tuple explanation is complicated by the fact that Scala has no good built-in arity abstractions. There are two main implicit conversions, but they are duplicated to some extent for N = 2-9 (N=1 is not a tuple and is handled separately, but similarly):

1) from (ScopedSetting[A], ScopedSetting[B], ...) to ApplyN, which provides the apply method

def apply[Z](f: (A,B,...) => Z): Initialize[Z]

This is used to define one setting in terms of another.

2) from (ScopedTaskable[A], ScopedTaskable[B], ...) to RichTaskableN, which provides:

def map[Z](f: (A,B,...) => Z): Initialize[Task[Z]]

This conversion is used to define tasks in terms of other settings (ScopedSetting[T]) and/or tasks (ScopedTask[T]).

> I have tried to be fairly responsive to questions related to 0.9.x.
> > Definitely don't wait three days before asking!
>
> As people seems to not be having problems, I thought it would probably be me
> missing something, so I tried to exhaust my cognitive skills before
> bothering, I don't like to ask things that are clearly defined in the
> manual.

I think the number of questions shows that there are problems, which is expected.

-Mark

[Randall R Schulz]

On Wednesday May 25 2011, Rodrigo Cano wrote:
> ...

>
> I tried reading Defaults.scala, using runMainTask as a reference, but
> I cant fully understand the code, because there are many implicit
> conversions I don't understand on which circumstances apply, so I
> couldn't extract much from It. Keys OTOH is fairly simple and useful.
>

> ...

IDEA's Scala plug-in shows where implicit conversions are used and
allows you to see which specific implicit conversions are applicable
and which among them is actually being used.

Randall Schulz