user confused with implicit variant based on package name

[j3k0]

In our apm repo, I have 2 packages named feathersui-source and feathersui-starling-compat.

[email protected] has a dependency over [email protected]

My project already has feathersui-source installed.

When I try to install feathersui-starling-compat it wouldn't do it, because feathersui-source version is larger that featherui-starling-compat version (which makes no sense, so I guess it's just confused).

$ apm install feathersui-starling-compat
[email protected]
Already installed: [email protected] [fovea] >= 1.0.0

---

feathersui-starling-compat/package.json

{
  "id": "feathersui-starling-compat",
  "name": "Feathers Starling Compat",
  "url": "https://github.com/BowlerHatLLC/feathersui-starling-compat",
  "docUrl": "https://github.com/BowlerHatLLC/feathersui-starling-compat",
  "description": "Backwards compatibility library to assist migration from Feathers 2.x to Feathers 3.x",
  "type": "src",
  "version": "1.0.0",
  "sourceUrl": "https://github.com/j3k0/feathersui-starling-compat/releases/download/v1.0.0/feathersui-starling-compat_1.0.0.airpackage",
  "dependencies": ["[email protected]", "starling-source:2.7.0"],
  "parameters": [],
  "tags": ["components", "gui", "starling", "ui", "widgets"]
}

[marchbold]

Please follow the guide on package identifiers. A hyphen indicates a variant.

https://github.com/airsdk/apm/wiki/Usage-CreatingPackages#identifier

[marchbold]

To elaborate here, you have created one package feathersui and two variants starling-compat and source

You probably meant featherui-source and feathersui.starling.compat

[j3k0]

OK. Maybe the variant thing could be more explicit?

See how Joshua is maintaining 2 mostly identical package.json files: https://github.com/feathersui/feathersui-starling

There could be a single package.json with this format:

{
  "id": "feathersui",
  "name": "feathersui",
  "url": "https://feathersui.com/as3-starling/",
  "docUrl": "https://feathersui/api-reference/",
  "description": "Cross-platform user interface components for creative frontend projects built with Starling",
  "variants": [{
    "type": "swc",
    "sourceUrl": "https://github.com/feathersui/feathersui-starling/releases/download/v4.2.0/feathersui_4.2.0.airpackage",
  }, {
    "name": "source",
    "type": "src",
    "sourceUrl": "https://github.com/feathersui/feathersui-starling/releases/download/v4.2.0/feathersui-source_4.2.0.airpackage",
  }],
  "version": "4.2.0",
  "dependencies": ["starling:2.7.0"],
  "parameters": [],
  "tags": ["components", "gui", "starling", "ui", "widgets"]
}

[marchbold]

There is more to a variant than just varying in the swc / source. Variants allow for different dependencies, tags, source and documentation so you'd practically be duplicating the entire file within itself.

[j3k0]

I get it, in my case I mostly always do only src and swc variants. Each "variants" could override only what needs to be (or everything).

Then having one file per variant I have to duplicate everything (and change all files for each new version)

When building I always have to make a small script like

cp package-src.json package.json
apm build
cp package-swc.json package.json
apm build

It would be nice if the tool could do something for us, like:

# apm build [directory] [variant]
apm build . src
apm build . swc

[j3k0]

...and if multi-variant package.json files are supported, then it could build them all in with only 1 command.

or maybe do this:

# apm build [directory] [variant...]
apm build . src swc

[marchbold]

We have spent a lot of time laying out all this functionality so I'll go through the thought process here around variants.

I think the key to remember here that the package.json isn't a build script but it's actually the package definition file that gets included inside the package and is used to identify the package later. I'm not sure it really makes sense to include information about other variants here? I suppose we could have apm deconstruct and reconstruct the appropriate contents for the package.json inside the airpackage at build time.

However we believed that having a unique file for each variant gave the publisher more control over the contents of the variant without over complicating the construction process. Eg, how are you going to handle different assets or platform configuration files (manifests/info additions etc), you would have a lot of extra information inside the package.json and then another level of directory structuring. A lot more places for a publisher to make mistakes, potentially end up with the wrong content in their package. A single source tree or swc based package really are the simplest cases and do not represent the complexity that a package can contain. Some of the packages have several dynamic frameworks, multiple static assets, 10+ manifest files, and a list of varying dependencies, all of which can be different between variants.

Not to mention every feature for a package that we add then has to account for this variant definition and the build process adapted. I think simplicity is key when starting out with a tool like this.

The way we approach this is we have scripts that handle the construction of the contents for a package including the package.json appropriate for the variant. We have placeholders for the common information and apply that before calling apm to build the package. If Josh wanted he could adapt his ant script quite easily (just adding some filter chains to his copy) to have a single package.json that was populated to be used for both of his packages and I think that is the better approach here.

If the confusion of the - (hyphen) usage is the main issue, perhaps what is needed is more clarity in the output from build, clearly showing the identifier and variant of the package you are building?

[j3k0]

I'm quite used to npm where this notion of variant didn't exist (as far as I know), so I just got caught myself going through the doc too quickly to notice there was this notion before publishing packages.

Having it explicitly in the package.json would have make it unmissable. A simpler solution could be to have:

{
  "id": "mypackage",
  "variant": "source"
}

This way, I can even use hyphens in the package id, it wouldn't be a problem. No implicit meaning.

---

A parallel I could also make, just as a food for thoughts, is the way .deb (Debian, Ubuntu) packages work: instead of listing explicit dependencies, it lists "features" it requires.

Made up example: the "wordpress" package requires the "mysql" feature. Many packages provides the "mysql" feature, there's one called mariadb, one called mysql. I myself can make a package, just installs haproxy with some rules to forward the 3306 port to another server.

If I maintain a fork of starling with some addons that Gamua don't like. I would'nt have to call my package "starling-*" in order to install "feathersui".

[j3k0]

Another question regarding variants and dependencies.

I see that feathersui-source depends on starling-source. What if I already have starling (swc) installed? Is apm expected to also install starling-source?

[marchbold]

If you have one of the variants installed already it will use that otherwise it will download the variant stated explicitly.

Variants should be completely interchangeable as a dependency.