Dev tools howto?

[Christian Johansen]

Hey,

Matthias/August: What's the current status of buster-dev-tools? I'm assuming that these docs are wrong? http://busterjs.org/docs/developers/ If dev-tools is currently working, could one of you update the docs to match so I can point people to it?

Christian

[Matthias Kling]

Indeed, it's mainly a) documenting the new options "pull"/"deps" (#136) and b) not recommending npm anymore but rather git only (pull#8 and here on Apr 17th) as far as I see. Maybe explicitly tell ppl to npm uninstall any older. It should be working, though, assuming you're using git only for it.
Anything I missed?

We already had several ppl getting confused so...
I could give it a try on Sunday; or maybe you wanna take care of it, August? I'm a bit short of time at the moment and buster-docs aren't fully working for me yet.

[Christian Johansen]

Trying out buster-dev-tools on Windows now, looks like it's working fine :) Nice work!

--
MVH
Christian

[Christian Johansen]

Question: We discussed having all the dependencies in a flat directory structure, and call the root directory node_modules. That way Node will find all dependencies without linking and so on. I see that buster-dev-tools does not install, copy or symlink buster dependencies, but it does not create node_modules. Is that intentional?

--
MVH
Christian

[August Lilleaas]

Which problem does the folder being named node_modules solve? You would need to set NODE_PATH anyway to make them requireable, and with NODE_PATH, the folder name is irrelevant.

[Christian Johansen]

No. If you lay out your projects like this:

projects/buster/
    node_modules/
        buster
        buster-amd
        buster-analyzer
        buster-args
        buster-assertions
        buster-autotest
        ...

Then node will find dependencies without any linking/copying, installing or NODE_PATH. The reason is that node finds packages by looking in ./node_modules, and then recursing through the parent directory, performing the same lookup until it hits /.

Christian

[Matthias Kling]

Oh, interesting. I must've missed the top node_modules/ part back then. But it looks strange, doesn't it?

In any case, we don't really have control over buster-dev-tools' parent folder's name. I don't think we can rename it programmatically and I don't think we should either.
So the question is: should we advise people to either
a) create that folder named node_modules and pull dev-tools into it
b) or set NODE_PATH (this could be automated and/or done on a per-shell basis if needed)

I'd opt for b) mostly because it's easier to explain and a little bit for aesthetic reasons.

[Christian Johansen]

My suggestion is that the process would look like this:

git clone https://github.com/busterjs/buster-dev-tools.git buster
cd buster
node bin/pull.js
ls node_modules
buster
buster-amd
...

In other words: dev tools creates node_modules in cwd and pulls all the buster projects down there. It's a setup that just works (tm) and requires no environment configuration at all. Pretty obvious choice IMHO.

Christian

--
MVH
Christian

[Matthias Kling]

Again, oh - didn't think of that :) So this is also viable and has the pro of not requiring adjusting env vars. Con is that buster projects are layed out flatly except for buster-dev-tools s.t. things we'd like most contribution to happen for are yet another level deeper under node_modules. Note that there are two main use cases for dev-env: 1. ppl just wanting the bleeding edge but not going to do dev and 2. "real" dev, i.e. possibly having several such structures side by side.

I'm not too passionate about either way; but still would tend a little more to using NODE_PATH. Easier to explain and doesn't require change in code (though small).

Got started with the docs today when after some time, errm, a little accident held me up from continuing. Will put up something soon though, but we need a decision on the layout / NODE_PATH question now. August?

[Matthias Kling]

docs updated to match the current status: 82bc4437, fixing #136.
Added css classes .input, .unix and .windows to replace <pre><kbd> and to support instructions for Unix and Windows side by side. Fixed Windows bug in docs server (705f07c0)

If we decide to not use NODE_PATH, buster-dev-tools should be adjusted first.

[Matthias Kling]

pull rq #15, for your convenience. Will amend it if we decide against NODE_PATH.

[August Lilleaas]

Pushed and deployed, http://busterjs.org/docs/developers/

I gave you push access to the buster-docs repo, send me your public key and I'll give you access to the web server too so you can deploy. The deploy script currently only works on linux, though. Doesn't even work on OS X due to bst tool differences :)

[Matthias Kling]

Cool, thanks :D mailed you the key. Not sure when I will find a solution for deploy, though.

I'd like to ask a question about the sed in bin/build:

  find static -name "*.html" | xargs sed -i s/\"index.html/"\"\/"/

  find static -name "*.html" | xargs sed -i s/index.html// 

It's the red part in the first sed that I don't understand: the first and third " (double quote) are not escaped, could they as well be left out? If so, I think I know what it does.
But I'm not sure if that's entirely correct. A lot of links to in-page anchors are broken, e.g. on http://busterjs.org/docs/args/ all the links in the code examples are broken, whereas the ones on the right (toc) are fine. Looks like simply leaving out the slash \/ in the first sed would fix it..?

[Christian Johansen]

The first sed convertst <a href="index.html"> into <a href="/">. The second one converts <a href="/some/path/index.html"> to <a href="/some/path/">. This is just to work around some quirks with the wget archiving option, because I really don't want "index.html" in URLs on the docs server.

To get this stuff running on Windows you should just set up Cygwin.

Christian

--
MVH
Christian

[meisl]

The first sed convertst <a href="index.html"> into <a href="/">

Understood ...and in e.g. a file /docs/args/index.html it converts <a href="index.html#createOption"> into <a href="/#createOption">, right?
That's the problem with e.g. http://busterjs.org/docs/args/: such links then effectively point to http://busterjs.org/#createOption (wrong) instead of to http://busterjs.org/docs/args/#createOption (right).

 

To get this stuff running on Windows you should just set up Cygwin.

Either that or implement in JS rather than as shell script, making it testable on the side ;)

[Christian Johansen]

On Tue, Apr 24, 2012 at 00:57, meisl <meisl...@googlemail.com> wrote:

The first sed convertst <a href="index.html"> into <a href="/">

Understood ...and in e.g. a file /docs/args/index.html it converts <a href="index.html#createOption"> into <a href="/#createOption">, right?
That's the problem with e.g. http://busterjs.org/docs/args/: such links then effectively point to http://busterjs.org/#createOption (wrong) instead of to http://busterjs.org/docs/args/#createOption (right).

Hmm, that seems wrong. I fixed these manually (i.e. converted the relative links to absolute ones) now, as I'm not entirely sure what else would break if I change the sed stuff :/

Christian

[meisl]

@malclocke found some more: #167

[meisl]

Just realized that I can run it with MINGW - which I already got through mysysgit.
I'll look into it and suggest we continue the links/anchor thing #167

[Christian Johansen]

Seems I fucked it up somehow? Feel free to fix the sed stuff, I'm not very attached to it ;)

--
MVH
Christian

[meisl]

Sure, Sir.
...actually I'm wondering - we could just do all of it as sed script? ;)

[meisl]

Done. Plz check #167.

[Christian Johansen]

Haha, that "sed all the things" thing was crazy.

Well done on fixing my crappy scripting, Matthias :)

--
MVH
Christian