About this document

This Kickstart tells you what you need to know to find and materialize distros using Cloudsmith.

You may find it helpful to read About Cloudsmith first, which explains the basics of how Cloudsmith works and how the site is organized.

You can consult our glossary for an explanation of unfamiliar terms used in this Kickstart.

Creating a Cloudsmith Identity


You do not need to create a Cloudsmith identity to use Cloudsmith to find and materialize configurations already published at Cloudsmith.	However, if you want to save or publish your own configurations at Cloudsmith, then you need to sign up for an account. Sign up requires only a valid email address.

Searching for a Configuration

Configurations are available at Cloudsmith either because a user published them to Cloudsmith, or because Cloudsmith found them when mapping a repository.

You can search for a configuration based on its name or terms mentioned in a short description created by its publisher. Search results can be narrowed or widened based on configuration types, which are selected in Search > Options. (Read on for more about configuration types.)

The search results list will be sorted by name and configuration type, and include links to summary pages (Distro Pages and/or Component Views) for each search result. An extract from the short description (if available) is also provided.

Hint: If you know what you are looking for, and just want to find and materialize it, you can keep things simple by:

using the default "distro" search
in the list of search results, navigating only to Distro Pages and ignoring all the other "views"
materializing the distro directly from its Distro Page
reading the basics of "materializing a configuration" below and skipping over the rest of this Kickstart.

Search options & configuration types

Cloudsmith configurations come in five different flavors or "types."

Component, the top-level configuration type, is just a way of saying that a given set of configurations represent the "same thing", and every configuration is associated with one.

Component Specification (CSPEC) is the next level in the hierarchy, and represents a specific "version" of that "thing."

When Cloudsmith finds configurations by mapping repositories, they will generally be available as one of these two types. (A user may also publish a configuration as a CSPEC/component in certain cases.)

The three other configuration types - Component Query (CQUERY), Bill of Materials (BOM) and Materialization Specification (MSPEC) - support different ways of selecting artifacts to "materialize" that configuration, such as "use latest" or "use fixed" version.

Cloudsmith searches for these configurations by default, since things that are "finished" (as opposed to works in progress)are typically published as one of these types.

All configuration types other than "component" can be materialized directly against the Cloudsmith site. We often refer to these as "distros," since you can "get" them via Cloudsmith.

Hint: If all you know is the name of what you are looking for, you may want to search only for configurations of the type "component", since that will give you the narrowest list of results. The search results listing will tell you how many versions each configuration has, and you can easily navigate to each version from the view for the component configuration.

Hint: If you are searching for the version of something with certain characteristics that the publisher may have mentioned in the short description (i.e. the version of YourConfig that supports version x of MyConfig), then you may want to search for CSPECs (i.e. versions) using "MyConfig" as the search term.

Hint: If you are searching for a configuration that has been published with the intention of being "consumed" by an end-user (for example a published open source distro), you may want to use the default search criteria ("MSPEC+BOM+CQUERY").

Navigating search results

You can review your search results by navigating among the Cloudpages that summarize what Cloudsmith knows abut available configurations.

Each configuration type has its own view. The views are linked so that you can navigate from the top-level component, to its available versions and then to the different materialization routes available for it.

An explanation of what is available in each view is found in Help > Page Context.

Note that each "distro" configuration also has a simpler view called a Distro Page, which is used as a destination for external links and to materialize the distro.

Materializing a configuration

Basics

You can materialize any distro directly from the Cloudsmith site. The only requirement on your end is that you have a browser capable of running a (signed) Java applet. You can materialize into a folder on your local machine or directly into an Eclipse project workspace, if Eclipse is installed.

The simplest way to materialize is by clicking the "materialize this" icon on a Distro Page. A Materialization Wizard will appear after several seconds and then will update and configure itself. This process can be nearly immediate, if you have recently used the wizard, or take up to several minutes, if you have not. A Cloudsmith splash screen will be visible while this takes place.

If the wizard fails to start, a troubleshooting wizard is available from the Distro Page to help you determine why.

Once the Materialization Wizard has configured itself, a dialog will appear to guide you through the materialization process. Online help files are linked through More Info in the dialog pages.

Dynamic materialization

An advanced materialization option is available for CSPEC or CQUERY-type distros. These distro types must be "resolved" into a bill of materials before being materialized.

If you materialize either distro type from its Distro Page and pre-existing resolution (i.e. a BOM-type distro) is unavailable, Cloudsmith will generate a temporary BOM to materialize. This temporary BOM will not have been tested, and may expose a flaw in the CSPEC or CQUERY that prevents it from being.

For this reason, a second materialization mechanism is provided directly on the distro's Cloudpage. You can find it be selecting Actions > Resolve & Materialize. This mechanism records error messages and allows you to save and examine the generated bill of materials to see what went wrong.

Repeat & Share

You may want to materialize a distro in exactly the same way as you did on a previous occasion. This may mean re-using the settings found in the Materialization Wizard, such as downloading a subset of the distro or selecting a given conflict resolution mechanism. Or, for a dynamic distro (i.e. a CQUERY) that resolves differently over time, this may mean getting the exact same set of artifacts as you got in the past.

You can use MSPECs to repeat a prior materialization. The final step of the Materialization Wizard allows you to save an MSPEC representing the completed resolution to your local machine. You can then publish this MSPEC at Cloudsmith and invite others to share, if appropriate.

To publish the MSPEC, go to Shortcuts > Publishing Wizard and publish the locally saved MSPEC. If you publish it to a private publishing space, you can invite others to share it. If you publish it to a public space, it will be available to all users.