Some terminology and basic concepts

[schomatis]

To add to the README. I'll keep updating the questions (and hopefully answers too) as I read through the code. Any additions/corrections are more than welcome.

Terms:

• Package: Any directory published through the gx publish command with its corresponding hash. This needs to be clearly differentiated from the Go concept of package, even though gx is language-agnostic its main consumer right now is gx-go so those two terms could be mixed up.

• DVCS Import: (Distributed?) Version Control System Import. I've mostly seen this in gx-go: path (or URI?) to import a package through its normal language package system, e.g., go get $DVCS_Import, where DVCS_Import=github.com/whyrusleeping/gx. Is this more aligned with the language or with the VCS? In the it's the second the example should be git clone $DVCS_Import. In simple terms: it's where I get the package other than through IPFS.

• package.json: This files serves multiple purposes. It identifies a directory as a gx package and provides (all?) the information about it.

• Dependencies. It's also a package. Install vs Import.

• Paths: The term package name is used for the name of directory that was published, but I would like to clarify what is its relevance in how packages are handled, as in the IPFS world everything is completely identified with hashes. The linkPackage functions uses the terms $GOPATH/src/gx/ipfs/$hash/$pkgname. How is a package identified? How important is the name of the directory inside the hash directory (which already uniquely identified the package)? And how is a gx path distinguished from the $GOPATH/src/$dvcsimport path, is that the DVCS Import path?

• gx-go vs gx install paths, the second one adds the gx/ipfs suffix (always?),

• gx-go tool, generic name, env tool? Is env normally the language name?

Random topics:

• Can gx work alone, or does it always need a companion language specific tool like gx-go?

• Dependency handling.

• It would be nice to add some explanation of how are paths rewritten, how is gx-go link used.

• Attributes of the base package.json, how does it distinguishes from a gx-go package.json file.

• How does IPFS fit into all this? Some explanation of the go-ipfs-api/shell.Shell structure is needed, does gx use a local IPFS repo or talks directly to the gateway? (See getLocalAPIShell()).

Many topics actually belong to the gx-go repo but it would be hard in the first iteration to write to separate but complementary documents as the two repos are tightly couple together (in the sense that presenting an example using only the gx command doesn't seem so relevant).

[schomatis]

So, since many of the ongoing efforts in making gx/gx-go more user-friendly involve the use and modifications of paths I would like to arrive at a clear and homogeneous terminology. The tricky part is to keep in mind that Gx should be language agnostic and clearly reflect that in the documentation, which I'm not going to do at the moment, in my mental model gx and gx-go are very coupled.

The objective is to subdivide the normal path of an installed package into different components that would make sense when reasoning about the code:

$GOPATH/src/gx/ipfs/QmHash/go-merkledag
           ^  ^           ^
                        (maybe)

• $GOPATH/ is the Go workspace, while inside of it $GOPATH/src is the directory with the Go source files. From the Gx perspective that's the install path.
• Inside of that Gx create another directory, $GOPATH/src/gx, normally implicit in the code (joined to the ipfs/<pkg-hash>/ as a single unit). That could be the Gx workspace, or the install path could be redefined to include this directory as I don't see much value in separating both paths but I don't think gx/ should be associated with the ipfs/<pkg-hash>/ part. (The value in distinguish them is that the Go import path starts from the gx/ part.)
• And here is where it starts to get muddy, normally a package would be installed in this Gx workspace under ipfs/<pkg-hash>/<pkg-name> (I would like to add a human-readable version for that in https://github.com/whyrusleeping/gx/issues/205 but for now let's suppose that's all there is).
  • So, from the IPFS perspective <pkg-hash>/ is a UnixFS directory obtained from the IPFS shell, and within that I'm using the package name. Is is worth to distinguish them? From the code perspective maybe not, but conceptually ipfs/<hash> was chosen specifically to respect a normal IPFS URI and <pkg-name>/ was added (I'm supposing) to make it easier to identify what that UnixFS directory contains (similar to a wrapper directory in ipfs add).

@Mr0grog I'm not sure how familiarized you are with the Gx package manager or its code, but any feedback you could add here (just from your experience and common sense) will be very valuable.

[Stebalien]

Note: We also rewrite the import paths in $GOPATH/gx/ipfs/... but not when checked into IPFS itself. Unfortunately, we need to do this because packages need to be able to refer to themselves.

[schomatis]

but not when checked into IPFS itself.

Not sure what "checked into" means in this context.

[Stebalien]

Not sure what "checked into" means in this context.

Sorry, I mean that they're not added to IPFS in the rewritten state. I like to point this out as cat $GOPATH/gx/ipfs/Qm.../my-pkg/thing.go won't return the same thing as ipfs cat /ipfs/Qm.../my-pkg/thing.go (which can be a bit confusing).