Layering Debugging Tips

UFO layering is a powerful ability. While some folks love layering, some dislike it. Think this is because layers are so powerful that they can get complex, especially when abused. It’s up to the welder of the sword. This doc tries to help you debug layering, even when abused. 🤣

Seeing Layers Clearly

Probably the best tip is to configure config.layering.show so you can see the layers.

Debugging: Showing Layers

You can show layers by setting config.layering.show = true

.ufo/config.rb

Ufo.configure do |config|
  config.layering.show = true
end

This will show the found variables layers. To see all possible layers, see: Debugging Layering Docs.

$ ufo build --no-docker
Config Layers
    .ufo/config.rb
    .ufo/config/web/base.rb
    .ufo/config/web/dev.rb
Building Task Definition
    .ufo/vars/base.rb
    .ufo/vars/dev.rb

All Layering

To see all the possible layers is to set UFO_LAYERS_ALL=1.

export UFO_LAYERS_ALL=1

There are many layers, so would just choose a few that work for your team and stick to those.

Config Layers
    .ufo/config.rb
    .ufo/config/base.rb
    .ufo/config/dev.rb
    .ufo/config/env.rb
    .ufo/config/env/base.rb
    .ufo/config/env/dev.rb
    .ufo/config/web.rb
    .ufo/config/web/base.rb
    .ufo/config/web/dev.rb
Building Task Definition
    .ufo/vars.rb
    .ufo/vars/base.rb
    .ufo/vars/dev.rb
    .ufo/vars/web.rb
    .ufo/vars/web/base.rb
    .ufo/vars/web/dev.rb
    .ufo/vars/demo.rb
    .ufo/vars/demo/base.rb
    .ufo/vars/demo/dev.rb
    .ufo/vars/demo/web.rb
    .ufo/vars/demo/web/base.rb
    .ufo/vars/demo/web/dev.rb

As you can see, layering can be pretty powerful but also complex.

Useful With

Showing layers to debug them is particularly useful when using:

App Layering

Reference

The table below covers each setting. Each option is configured in .ufo/config.rb with config.OPTION. The config. portion is not shown for conciseness. IE: logger.level vs config.logger.level.

Name	Default	Description
layering.show	false	Shows used layers for both config and vars. Useful for debugging layers. There are nuances with this option. It should be set in `.ufo/config.rb` and not be set dynamically. So only `true` or `false` values should be used. This is because config layers are processed so early that UFO parses the config file for this value internally.
layering.show_for_commands	%w[build ship]	Which ufo commands to show layering for. Useful for debugging layers. There are nuances with this option. It should be set in `.ufo/config.rb` and not be set dynamically. So only array values should be used. This is because config layers are processed so early that UFO parses the config file for this value internally.

See Full Config Reference

Getting Started