[Scons-dev] API for warnings and debug messages

[anatoly techtonik]

On Wed, May 28, 2014 at 8:59 PM, Kenny, Jason L <jason.l.kenny at intel.com>wrote:

>  I agree it look complex, but it is not that bad…
>

Here is my first look.

== Problem outline is good, needs more time to become obvious ==

I like the idea to make 100% cover of all possible inputs/outputs (text
data that comes out and into SCons). The diagram is not enough to
illustrate the concept and requires reading the doc thoroughly. I started
to draw it again:

https://docs.google.com/drawings/d/13Ibva0qyYtEJq9enYkA3kj93ANAONduLxeE7I2H9l4k/edit

There are many parts that seems evident, but for most people they are new,
so they need to be explained, and better to have one picture per one
concept. Just more time to polish.

== output.py ==

It is just a bunch of functions. I see there are some magic string like
"sep", but no explanation, and for the first look I can not really
investigate deeper. My use case - I have an external debugger and I want to
see what SCons does _without modifying_ SCons. I want to filter messages,
get into more deep level of detail (1-9), or to turn off processing at all
to speed up the process. How can I turn off processing for all these
functions? How can I replace the function? How can I filter error or
warning, how can I get only specific errors and warnings for my output? So,
I need to filter both error_ and warning_ functions, and all others as well.

I see that we will just reimplement logging the Java way coming through the
same trapdoor.

== Easy logging for the start, overengineering later ==

Python is good for prototyping. Why not to start from scratch and make the
most simple system possible. Just one function that produces strings. Let's
call it probe(). How would you produce strings is another question. If we
need a component name, we produce it like:

   probe("component: created object")

What probe does is up to you. It is overridable function - by SConstruct,
by external tool, by anything. The only restriction is that any
modification to probe() is itself logged. Who when where changed probe.
This can be just a memory log. I want logging to be completely decoupled
from the program (or as decoupled as possible). Like in real world you can
tap to wires to eavesdrop without performance penalty - the same interface
should be possible in open source world, and it will be good if SCons can
provide one. Not sure about implementation, but in the end I see it as an
external monitor that connects to SCons and reacts to some events that
appear through the probe() function. If probe() is implemented blocking -
this can be used to control speed of execution.

== On big chunk problem ==

I need more time to review the document. It is much easier to review stuff
if you have one real world user story to tackle at a time. Story first -
theory second. Right now I'll just wait for the next chunk of free time to
come.


>  It mostly about taking output from different sources and putting it
> together allowing for coloring, no mangled text ( as we get with raw scons
> and a –j based build). Each part is simple and does a simple thing. What I
> was suggesting here was more of a view to add a SCons.api.output module
> that has some sort of error_msg(), warning_msg() etc… This allow an easy
> way to standardize output formats. For verbose and or debugging messages it
> can be very useful to allow for a filter logic.
>

This is just a formatting API.
http://techtonik.rainforce.org/2013/02/formatting-api-anti-pattern.html

What is important is to understand where messages are coming from, where
they end, what is the processing logic, how do you define a message, why do
you define a message, to analyze the data structure first. Who said that we
only have debugs and warnings? What if we need 10 different circles of
messages on one axis and different components on another? How to query
about available components that can be turned on and off to produce
messages?


>  What I have is simple in this.
>
>
>
> You can say –verbose=<type>,<type1> on the commandline and only
> verbose_msg(“type”,”message”) will print. This makes for a simple API to
> output stuff. And control what gets outputted vs the dump everything and
> grep logic that is common.
>
>
>
> With this, what it does under the covers can change to do different things
> as found to be useful. Having an API that is clear I feel is more useful.
>

Problem is that, as a user, I don't know which type of message I need to
debug some issue. I error message (traceback) contains the command that I
can type to get more info - that will help.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://two.pairlist.net/pipermail/scons-dev/attachments/20140529/078462f9/attachment-0001.html>