proposed common-js file moves/renames for post-1.5

[Patrick Mueller <pm...@gmail.com>]

I finally got a chance to start looking at the common-js bits this week.

One thing that's had me confused, is figuring out how all the files get
combined into the platform-specific single files.  It's not real obvious
from looking at the files, or the resulting output.  Looking at the
packager.js script gives you the recipe, but it's nice to see the whole
thing laid out.  Which I couldn't see.

I instrumented packager.js to dump the module names and original file names
of the source.  The result is here:


https://github.com/pmuellr/incubator-cordova-js/wiki/cordova-js-file-to-module-map

(neat that you can enabled a wiki on your cloned GitHub repos!)

On the left is the module id, the right is the original file name.

Based on that, came up with a few thoughts on a clearer organization of the
.js files, here:


https://github.com/pmuellr/incubator-cordova-js/wiki/cordova-js-file-location-refactoring

It seems to me like we should be able to do a little re-org of the files,
with changes to packager.js, to make things a little more obvious.  All
without changing any of the actual code - just the file names/directories,
and packager.js

Changes:

- rename `lib` to `cordova`, since that's the top level module bit in our
modules

- move the platform-specific modules out of `lib`, into a new top-level
directory named `platform`, which has subdirectories for each platform, and
then cordova/blah/... directories for any additional files for the
platform, including potentially overlaid files

- there are also plain ol' scripts like `require.js` which should be
separate from the modules, in say a top-level `scripts` directory

All that would, I think, be a little clearer.  And would likely simplify
packager.js.  Would also easily allow you to 'overlay' a platform-specific
file over a common one, if you wanted.

If we had a 'portable' version of `cordova/exec.js` and
`cordova/platform.js`, that existed in the portable directory but was
always overwritten by platform builds, then the `cordova` directory could
actually be the source for a "mock" version of Cordova - that you could
load in a desktop browser, say.  In theory, it would be easy to ingest this
kind of directory structure in an AMD environment as well.

I would also really like to create a subdirectory-per-plugin in the
`plugins` directory, but this will affect other code, since those modules
names will be changing.  It's a step in the direction of "all our plugins
are just like any other plugins".  Due to the code changes required,
wouldn't be including this in the first refactor.

I was thinking this might be something we could do post-1.5.  Thought I'd
go ahead and start playing with it, see how it feels.  Anyone have
thoughts, or know of any reason why this wouldn't work, or be more
confusing than the current layout?

-- 
Patrick Mueller
http://muellerware.org

Re: proposed common-js file moves/renames for post-1.5

[Bryce Curtis <cu...@gmail.com>]

+1 for restructure of cordova-js.

One issue that I see as unnecessary and a source of error is checking in
cordova.android.js into the android repository.  As developers we already
have to be able to build cordova-js and then copy it under the platform.
 So, any change to cordova-js also requires a corresponding check-in to
each of the platform repositories.  Right now that's only Android, but as
the rest move to cordova-js, it will be iOS, BB, WP7, bada, ... - well, you
get the idea.  I suggest we only do the merge when packaging up a release.

On Tue, Feb 28, 2012 at 11:09 AM, Patrick Mueller <pm...@gmail.com> wrote:

> On Tue, Feb 28, 2012 at 12:00, Filip Maj <fi...@adobe.com> wrote:
>
> > Yeah I like it overall. I'll file it in JIRA and set it up for post-1.5.
> >
> > I am not sure I like the index.js thing but I don't know why ;)
>
>
> Honestly, not a big fan of <name>/index.js matching "name"; but let's see;
> the index.js thing is one of the conventions of node ...
>
> --
> Patrick Mueller
> http://muellerware.org
>

Re: proposed common-js file moves/renames for post-1.5

[Patrick Mueller <pm...@gmail.com>]

On Tue, Feb 28, 2012 at 12:00, Filip Maj <fi...@adobe.com> wrote:

> Yeah I like it overall. I'll file it in JIRA and set it up for post-1.5.
>
> I am not sure I like the index.js thing but I don't know why ;)


Honestly, not a big fan of <name>/index.js matching "name"; but let's see;
the index.js thing is one of the conventions of node ...

-- 
Patrick Mueller
http://muellerware.org

Re: proposed common-js file moves/renames for post-1.5

[Filip Maj <fi...@adobe.com>]

Yeah I like it overall. I'll file it in JIRA and set it up for post-1.5.

I am not sure I like the index.js thingŠ but I don't know why ;)

On 2/24/12 8:11 AM, "Patrick Mueller" <pm...@gmail.com> wrote:

>On Fri, Feb 24, 2012 at 10:39, Drew Walters <de...@gmail.com> wrote:
>
>> > - move the platform-specific modules out of `lib`, into a new
>>top-level
>> > directory named `platform`, which has subdirectories for each
>>platform,
>> and
>> > then cordova/blah/... directories for any additional files for the
>> > platform, including potentially overlaid files
>> I don't understand why this would be a peer of `lib` and not a child.
>> In your examples you list 'platform/android/cordova/exec.js'. This
>> seems to imply that the platform specific files could apply to more
>> then just cordova since cordova would be a child.
>>
>
>Right; there would be multiple `cordova` subdirectories in the tree:
>
>   cordova-js/cordova/... - all the portable stuff
>   cordova-js/platform/android/cordova - all the android specfic stuff
>   cordova-js/platform/ios/cordova - all the ios specfic stuff
>
>So, yes, I would expect that platforms could supply modules "outside" of
>the cordova module-id-space.  So, there might exist a file
>
>   cordova-js/platform/android/my-coolio-stuff.js
>
>This would end up getting built as a top-level 'my-coolio-stuff' module -
>require('my-coolio-stuff') would return that module, for android.
>
>But I don't expect that we would actually do that.  The reason to have the
>cordova directory IN the `cordova/platform/android` directory, is so that
>the directories of the modules line up with the module ids that we
>generate.  Otherwise, you'll need to do the translation everytime you see
>
>    cordova-js/platform/android/app.js
>
>and realize - "oh that's actually the module 'cordova/app'
>
>
>> Unless there is a
>> reason for this, I still like 'cordova/platform/android/exec' better.
>> Seems to me we would want to keep the module namespace beneath
>> 'cordova'.
>>
>
>To be more specific:
>
>- rename `~/lib` to `~/cordova`; there is no more `~/lib`.
>- mkdir ~/platform
>- mkdir ~/platform/android
>- mkdir ~/platform/...
>- move platform-specific stuff in ~/cordova (was ~/lib), in such a way as
>each module exists in a path associated with it's eventual module id,
>prefixed by `~/platform/[whicheverPlatform]`
>- move non-modules into a 'new' `~/lib` directory; it's more than just
>require.js - bootstrap, etc
>
>Now, to do a build for a platform:
>- collect as modules all files from ~/cordova
>- collect as modules all files from ~/platform/[whicheverPlatform]/cordova
>- collect as scripts all files from ~/lib
>
>bonusi:
>
>- the files are laid out exactly as the modules will be named, modulo
>platform-specific prefix directories for platform-specific files; no more
>in-head conversion when I'm looking at directory listings of modules.
>
>- no more logic in the build script, just three "virtual" `cp -R`s.
>
>- prolly easy to use with requirejs et al
>
> > - there are also plain ol' scripts like `require.js` which should be
>
>> > separate from the modules, in say a top-level `scripts` directory
>> +1 though I think require.js is the only example of this so far and I
>> would vote for keeping it under 'cordova' name space and in a 'lib'
>> folder (showing my C roots).
>>
>
>Pretty sure it's more than require.js.  And `scripts` makes more sense to
>me than `lib`.
>
>-- 
>Patrick Mueller
>http://muellerware.org

Re: proposed common-js file moves/renames for post-1.5

[Patrick Mueller <pm...@gmail.com>]

On Fri, Feb 24, 2012 at 10:39, Drew Walters <de...@gmail.com> wrote:

> > - move the platform-specific modules out of `lib`, into a new top-level
> > directory named `platform`, which has subdirectories for each platform,
> and
> > then cordova/blah/... directories for any additional files for the
> > platform, including potentially overlaid files
> I don't understand why this would be a peer of `lib` and not a child.
> In your examples you list 'platform/android/cordova/exec.js'. This
> seems to imply that the platform specific files could apply to more
> then just cordova since cordova would be a child.
>

Right; there would be multiple `cordova` subdirectories in the tree:

   cordova-js/cordova/... - all the portable stuff
   cordova-js/platform/android/cordova - all the android specfic stuff
   cordova-js/platform/ios/cordova - all the ios specfic stuff

So, yes, I would expect that platforms could supply modules "outside" of
the cordova module-id-space.  So, there might exist a file

   cordova-js/platform/android/my-coolio-stuff.js

This would end up getting built as a top-level 'my-coolio-stuff' module -
require('my-coolio-stuff') would return that module, for android.

But I don't expect that we would actually do that.  The reason to have the
cordova directory IN the `cordova/platform/android` directory, is so that
the directories of the modules line up with the module ids that we
generate.  Otherwise, you'll need to do the translation everytime you see

    cordova-js/platform/android/app.js

and realize - "oh that's actually the module 'cordova/app'


> Unless there is a
> reason for this, I still like 'cordova/platform/android/exec' better.
> Seems to me we would want to keep the module namespace beneath
> 'cordova'.
>

To be more specific:

- rename `~/lib` to `~/cordova`; there is no more `~/lib`.
- mkdir ~/platform
- mkdir ~/platform/android
- mkdir ~/platform/...
- move platform-specific stuff in ~/cordova (was ~/lib), in such a way as
each module exists in a path associated with it's eventual module id,
prefixed by `~/platform/[whicheverPlatform]`
- move non-modules into a 'new' `~/lib` directory; it's more than just
require.js - bootstrap, etc

Now, to do a build for a platform:
- collect as modules all files from ~/cordova
- collect as modules all files from ~/platform/[whicheverPlatform]/cordova
- collect as scripts all files from ~/lib

bonusi:

- the files are laid out exactly as the modules will be named, modulo
platform-specific prefix directories for platform-specific files; no more
in-head conversion when I'm looking at directory listings of modules.

- no more logic in the build script, just three "virtual" `cp -R`s.

- prolly easy to use with requirejs et al

 > - there are also plain ol' scripts like `require.js` which should be

> > separate from the modules, in say a top-level `scripts` directory
> +1 though I think require.js is the only example of this so far and I
> would vote for keeping it under 'cordova' name space and in a 'lib'
> folder (showing my C roots).
>

Pretty sure it's more than require.js.  And `scripts` makes more sense to
me than `lib`.

-- 
Patrick Mueller
http://muellerware.org

Re: proposed common-js file moves/renames for post-1.5

[Drew Walters <de...@gmail.com>]

> - rename `lib` to `cordova`, since that's the top level module bit in our
> modules
+1

> - move the platform-specific modules out of `lib`, into a new top-level
> directory named `platform`, which has subdirectories for each platform, and
> then cordova/blah/... directories for any additional files for the
> platform, including potentially overlaid files
I don't understand why this would be a peer of `lib` and not a child.
In your examples you list 'platform/android/cordova/exec.js'. This
seems to imply that the platform specific files could apply to more
then just cordova since cordova would be a child.  Unless there is a
reason for this, I still like 'cordova/platform/android/exec' better.
Seems to me we would want to keep the module namespace beneath
'cordova'.

> - there are also plain ol' scripts like `require.js` which should be
> separate from the modules, in say a top-level `scripts` directory
+1 though I think require.js is the only example of this so far and I
would vote for keeping it under 'cordova' name space and in a 'lib'
folder (showing my C roots).

> I would also really like to create a subdirectory-per-plugin in the
> `plugins` directory
+1 As we more closely tie native plugin code to JS API from a
packaging standpoint I think this needs to be done for manageability.

On your wiki entry, the following example for 'moving platform files
to separate directories' seems excessive:
    platform/android/cordova/plugin/android/app

Based on my comments above I still like this better:
    cordova/platform/android/plugin/app

Just my thoughts.

On Thu, Feb 23, 2012 at 10:07 PM, Patrick Mueller <pm...@gmail.com> wrote:
> I finally got a chance to start looking at the common-js bits this week.
>
> One thing that's had me confused, is figuring out how all the files get
> combined into the platform-specific single files.  It's not real obvious
> from looking at the files, or the resulting output.  Looking at the
> packager.js script gives you the recipe, but it's nice to see the whole
> thing laid out.  Which I couldn't see.
>
> I instrumented packager.js to dump the module names and original file names
> of the source.  The result is here:
>
>
> https://github.com/pmuellr/incubator-cordova-js/wiki/cordova-js-file-to-module-map
>
> (neat that you can enabled a wiki on your cloned GitHub repos!)
>
> On the left is the module id, the right is the original file name.
>
> Based on that, came up with a few thoughts on a clearer organization of the
> .js files, here:
>
>
> https://github.com/pmuellr/incubator-cordova-js/wiki/cordova-js-file-location-refactoring
>
> It seems to me like we should be able to do a little re-org of the files,
> with changes to packager.js, to make things a little more obvious.  All
> without changing any of the actual code - just the file names/directories,
> and packager.js
>
> Changes:
>
> - rename `lib` to `cordova`, since that's the top level module bit in our
> modules
>
> - move the platform-specific modules out of `lib`, into a new top-level
> directory named `platform`, which has subdirectories for each platform, and
> then cordova/blah/... directories for any additional files for the
> platform, including potentially overlaid files
>
> - there are also plain ol' scripts like `require.js` which should be
> separate from the modules, in say a top-level `scripts` directory
>
> All that would, I think, be a little clearer.  And would likely simplify
> packager.js.  Would also easily allow you to 'overlay' a platform-specific
> file over a common one, if you wanted.
>
> If we had a 'portable' version of `cordova/exec.js` and
> `cordova/platform.js`, that existed in the portable directory but was
> always overwritten by platform builds, then the `cordova` directory could
> actually be the source for a "mock" version of Cordova - that you could
> load in a desktop browser, say.  In theory, it would be easy to ingest this
> kind of directory structure in an AMD environment as well.
>
> I would also really like to create a subdirectory-per-plugin in the
> `plugins` directory, but this will affect other code, since those modules
> names will be changing.  It's a step in the direction of "all our plugins
> are just like any other plugins".  Due to the code changes required,
> wouldn't be including this in the first refactor.
>
> I was thinking this might be something we could do post-1.5.  Thought I'd
> go ahead and start playing with it, see how it feels.  Anyone have
> thoughts, or know of any reason why this wouldn't work, or be more
> confusing than the current layout?
>
> --
> Patrick Mueller
> http://muellerware.org