[webkit-dev] Some text about the B3 compiler

Filip Pizlo fpizlo at apple.com
Fri Jan 29 15:09:34 PST 2016 

Follow up on this:

> On Jan 29, 2016, at 11:38 AM, Filip Pizlo <fpizlo at apple.com> wrote:
> 
> I started coverting the documentation to Markdown.  I don’t think this is a good idea.
> 
> - Markdown has no definition lists.  The entire IR document is a definition list.  I don’t want B3’s documentation to be blocked on this issue.

It turns out that it does have them, but they are very weak.  For example, you can’t have code blocks or paragraphs inside them.  We want to have code blocks inside opcode definitions, to show examples.

> - Markdown’s conversion step makes the workflow awkward.  I’m not going to use some Markdown editing app - that will prevent me from being able to properly format code examples.  I need a code editor for that.

This was hard to get around.  This isn’t a problem with Markdown, but rather, a problem with using Wordpress to render Markdown that is in svn.  There is no way to preview the Markdown before committing it.  That would lead to unusual problems, where after a patch is landed, the patch author or someone else would have to do a bunch of blind follow-up commits to fix any style issues, like code blocks that don’t fit properly or whatever.

Considering that we will have to be hacking raw HTML inside those Markdown files (due to definition lists), the lack of preview basically means that you have no way of predicting what the your HTML will render like.

> 
> I think that this documentation should be HTML.  I don’t think we should expend a lot of energy to formatting it nicely.  The point of this document is for it to be read by engineers while they hack code.

I landed raw HTML documentation: http://trac.webkit.org/changeset/195841 <http://trac.webkit.org/changeset/195841>

I filed this bug about improving its style: https://bugs.webkit.org/show_bug.cgi?id=153674 <https://bugs.webkit.org/show_bug.cgi?id=153674>

-Filip


> 
> -Filip
> 
> 
>> On Jan 29, 2016, at 10:12 AM, Timothy Hatcher <timothy at apple.com <mailto:timothy at apple.com>> wrote:
>> 
>> I also added:
>> 
>> https://webkit.org/documentation/b3/air/ <https://webkit.org/documentation/b3/air/> loads /docs/b3/assembly-intermediate-representation.md
>> 
>>> On Jan 29, 2016, at 10:05 AM, Filip Pizło <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>> 
>>> Thank you!  I'll convert them today. 
>>> 
>>> -Filip
>>> 
>>> On Jan 29, 2016, at 10:02 AM, Timothy Hatcher <timothy at apple.com <mailto:timothy at apple.com>> wrote:
>>> 
>>>> Markdown is pretty similar to the wiki formatting and very simple.
>>>> 
>>>> You can look at a cheatsheet if you login to the blog: https://webkit.org/wp/wp-admin/post.php?post=4300&action=edit <https://webkit.org/wp/wp-admin/post.php?post=4300&action=edit>
>>>> 
>>>> I have also used this HTML to Markdown converter before: http://domchristie.github.io/to-markdown/ <http://domchristie.github.io/to-markdown/>
>>>> 
>>>> The pages are created:
>>>> 
>>>> https://webkit.org/documentation/b3/ <https://webkit.org/documentation/b3/> loads /docs/b3/bare-bones-backend.md
>>>> https://webkit.org/documentation/b3/intermediate-representation/ <https://webkit.org/documentation/b3/intermediate-representation/> loads /docs/b3/intermediate-representation.md
>>>> 
>>>> Once those files are added to SVN, they will get picked up by the site. I can change those to point to other names if you want something different.
>>>> 
>>>> — Timothy Hatcher
>>>> 
>>>>> On Jan 29, 2016, at 9:34 AM, saam barati <saambarati1 at gmail.com <mailto:saambarati1 at gmail.com>> wrote:
>>>>> 
>>>>> I'm happy to convert the document to markdown. Can you send me your latest revision or post it to the website?
>>>>> 
>>>>> I usually look at:
>>>>> http://daringfireball.net/projects/markdown/syntax <http://daringfireball.net/projects/markdown/syntax>
>>>>> For a refresher on the syntax.
>>>>> 
>>>>> Tim, could you create a page that loads the markdown file?
>>>>> 
>>>>> Thanks,
>>>>> Saam
>>>>> 
>>>>> On Jan 29, 2016, at 12:06 AM, Filip Pizło <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>>>> 
>>>>>> I'm all for this but I don't know anything about markdown. 
>>>>>> 
>>>>>> What's the best way to proceed?
>>>>>> 
>>>>>> -Filip
>>>>>> 
>>>>>> On Jan 28, 2016, at 9:24 PM, Timothy Hatcher <timothy at apple.com <mailto:timothy at apple.com>> wrote:
>>>>>> 
>>>>>>> They should be markdown files like we do for the code style and policy documents.
>>>>>>> 
>>>>>>> https://trac.webkit.org/browser/trunk/Websites/webkit.org/code-style.md <https://trac.webkit.org/browser/trunk/Websites/webkit.org/code-style.md>
>>>>>>> 
>>>>>>> We can then make Wordpress pages on the site that load the markdown.
>>>>>>> 
>>>>>>> Maybe put them in a /docs/b3/ directory?
>>>>>>> 
>>>>>>> — Timothy Hatcher
>>>>>>> 
>>>>>>> On Jan 28, 2016, at 4:48 PM, Filip Pizlo <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>>>>>> 
>>>>>>>> I guess we could put it in Websites/webkit.org/b3 <http://webkit.org/b3>.  Then patches could edit both B3 and the documentation in one go, and the documentation would go live when it’s committed.
>>>>>>>> 
>>>>>>>> Does anyone object to this?
>>>>>>>> 
>>>>>>>> -Filip
>>>>>>>> 
>>>>>>>> 
>>>>>>>>> On Jan 28, 2016, at 4:39 PM, Saam barati <sbarati at apple.com <mailto:sbarati at apple.com>> wrote:
>>>>>>>>> 
>>>>>>>>> Yeah. That’d be the easiest way to keep it up IMO.
>>>>>>>>> 
>>>>>>>>> Saam
>>>>>>>>> 
>>>>>>>>>> On Jan 28, 2016, at 4:37 PM, Filip Pizło <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>>>>>>>>> 
>>>>>>>>>> +1
>>>>>>>>>> 
>>>>>>>>>> Do you think we should move the documentation to a file in svn so that it can be reviewed as part of patch review?
>>>>>>>>>> 
>>>>>>>>>> -Filip
>>>>>>>>>> 
>>>>>>>>>> On Jan 28, 2016, at 4:32 PM, Saam barati <sbarati at apple.com <mailto:sbarati at apple.com>> wrote:
>>>>>>>>>> 
>>>>>>>>>>> This is great. Thanks Fil.
>>>>>>>>>>> 
>>>>>>>>>>> I propose that we do all that we can to keep this updated.
>>>>>>>>>>> I suggest that all patches that change to the IR should also include with it 
>>>>>>>>>>> a change to the documentation, and that reviewers should require this.
>>>>>>>>>>> 
>>>>>>>>>>> It’d also be great if other significant changes that seem like the deserve
>>>>>>>>>>> a mention in the documentation also get added as part of patches.
>>>>>>>>>>> 
>>>>>>>>>>> Saam
>>>>>>>>>>> 
>>>>>>>>>>>> On Jan 28, 2016, at 4:23 PM, Filip Pizlo <fpizlo at apple.com <mailto:fpizlo at apple.com>> wrote:
>>>>>>>>>>>> 
>>>>>>>>>>>> Hi everyone,
>>>>>>>>>>>> 
>>>>>>>>>>>> We’ve been working on a new compiler backend for the FTL JIT, which we call B3.  It stands for “Bare Bones Backend”.  We recently enabled it on X86/Mac, and we’re working hard to enable it on other platforms.
>>>>>>>>>>>> 
>>>>>>>>>>>> If you’re interested in how it works, I’ve started writing documentation.  I’ll be adding more to it soon!
>>>>>>>>>>>> https://trac.webkit.org/wiki/BareBonesBackend <https://trac.webkit.org/wiki/BareBonesBackend>
>>>>>>>>>>>> https://trac.webkit.org/wiki/B3IntermediateRepresentation <https://trac.webkit.org/wiki/B3IntermediateRepresentation>
>>>>>>>>>>>> 
>>>>>>>>>>>> -Filip
>>>>>>>>>>>> 
>>>>>>>>>>>> _______________________________________________
>>>>>>>>>>>> webkit-dev mailing list
>>>>>>>>>>>> webkit-dev at lists.webkit.org <mailto:webkit-dev at lists.webkit.org>
>>>>>>>>>>>> https://lists.webkit.org/mailman/listinfo/webkit-dev <https://lists.webkit.org/mailman/listinfo/webkit-dev>
>>>>>>>>>>> 
>>>>>>>>> 
>>>>>>>> 
>>>>>>>> _______________________________________________
>>>>>>>> webkit-dev mailing list
>>>>>>>> webkit-dev at lists.webkit.org <mailto:webkit-dev at lists.webkit.org>
>>>>>>>> https://lists.webkit.org/mailman/listinfo/webkit-dev <https://lists.webkit.org/mailman/listinfo/webkit-dev>
>>>>>> _______________________________________________
>>>>>> webkit-dev mailing list
>>>>>> webkit-dev at lists.webkit.org <mailto:webkit-dev at lists.webkit.org>
>>>>>> https://lists.webkit.org/mailman/listinfo/webkit-dev <https://lists.webkit.org/mailman/listinfo/webkit-dev>
>>>> 
>> 
> 
> _______________________________________________
> webkit-dev mailing list
> webkit-dev at lists.webkit.org
> https://lists.webkit.org/mailman/listinfo/webkit-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.webkit.org/pipermail/webkit-dev/attachments/20160129/80f2c621/attachment.html>

More information about the webkit-dev mailing list