Install Conventions

Just an update that we have tightened down the installation and uninstallation algorithm a bit. It is still ForgeBox specific and doesn’t account for nested modules, but that will come in another version :slight_smile: We will be documenting this soon in the usage docs that I have already started writing but for now I wanted to put it here for comments and testing.

Also, if you Preside guys see this, these updates mean you should be able to remove the directory property from your box.json altogether. People don’t need to specify a directory either. CommandBox will recognize that it is installing a command and place it in the user/.CommandBox/commands folder automatically.

Also, your package zip file doesn’t need any folders in the root unless they are part of the package. We’re following NPMs convention where the package manager creates the folder automatically to place your package in and the zip file is unpacked right there. That means box.json and all top level files should just be in the root of the zip.

  1. Verify the slug against ForgeBox

  2. If not found, error

  3. Get slug information

  4. Using that information, we verify if we have the package in the local cache according to version received

  5. Download the package and place it in our artifacts cache according to our convention

  6. package-name/version

  7. Get descriptor data, if none found, everything is defaulted.

  8. Installation Location

  9. If directory parameter is provided, use it

  10. If directory box.config property is set, then we use it,

  11. if type box.json property is set then use the conventions

  12. commandbox-commands – placed in user command directory

  13. modules – placed in modules directory

  14. plugins – placed in plugins directory and createPackageDirectory set to false

  15. interceptors – placed in interceptors directory and createPackageDirectory set to false

  16. Else CWD

  17. Directory Name

  18. if createPackageDirectory box.json property is set to false in the target package, the package will be unpacked directly into the install location. These packages cannot be uninstalled since they aren’t contained in a folder of their own.

  19. The name of the package is appended to the installation directory by convention

  20. Special Exceptions: The following special exception are needed for compatibility with our other installation tools and the lack of versions in ForgeBox. They can be removed later once we update all tools.

  21. If the slug matches the internal folder in the root of the package, then we use that for installation

  22. If a packageDirectory box.json property is set, then we will override the slug package container name

  23. Updating the box.json

  24. All dependencies are saved to box.json by default (created if it doesn’t exist).

  25. Save as dev dependency with --saveDev

  26. Turn off saving with --!save

  27. If the package was installed in a dedicated directory, update the installPath property of box.json to store where it was installed to. This makes uninstall possible without forcing conventions on the user.

Thanks for this Brad. One thing we found a little awkward is that for commandbox commands, the slug of the project ends up being the namespace of the commands and that is not ideal imo. We want the commandbox namespace to be “preside”, but that is not appropriate for the slug of the project which is not preside itself, but just commands for preside (preside-commandbox-commands might be more appropriate). Perhaps command namespaces could be calculated from the root of each subfolder under /user/.CommandBox/commands? i.e.

.CommandBox
—commands
------preside-commandbox-commands
---------preside
------------new
---------------site.cfc
------------start.cfc

Ideally for us, that would give you the commands “preside new site” and “preside start”.

Hmm, good points Dominic. One thought is that you can put anything you want in the alias for a command, even overriding an existing command.

I’m thinking maybe we should just skip the package-named directory for commands. I’m already doing this now with interceptors and plugins-- they are just dumped in the convention location without any subfolder. The more I think about it, the more sense it makes and it’s just one more line of code. I probably would have done that last night if I was thinking about it. it’s really almost mandatory since people can make commands with no namespace which means they need to be in the root of the commands folder.

The only big drawback of not installing a package into a subdirectory is that it can’t be uninstalled with the uninstall command. Come to think of it, I’m not sure installing a command should save to box.json either. It’s not really a dependency of that site (not even a dev dependency), it’s just part of the tooling.

Thanks!

~Brad

ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com

OK, I updated the bleeding edge to drop commands in the commands directory without the subfolder named after the slug. I need to create some test commands on ForgeBox so I can test this easier. Right now Preside is the only one :slight_smile:

Thanks!

~Brad

ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com

I created another CommandBox command in ForgeBox so the Preside command wouldn’t be lonely :slight_smile:

http://www.coldbox.org/forgebox/view/CommandBox-Chuck-Norris

You too, can have it by typing:

install commandbox-chuck-norris

Thanks!

~Brad

ColdBox Platform Evangelist
Ortus Solutions, Corp

E-mail: brad@coldbox.org
ColdBox Platform: http://www.coldbox.org
Blog: http://www.codersrevolution.com