2

I've been hunting for detailed documentation on what goes into a Berksfile, but all I've found is examples, and "you can do this" informal stuff. (This includes the material at http://berkshelf.com ...)

Q1: What is the basic syntax of a Berksfile?

Q2: What is the (complete) list of "declarations" that can go into a Berksfile?

Q3: A "cookbook" declaration takes an optional hash parameter. What is the (complete) list of options that is supported by vanilla Berkshelf?

Stephen C
  • 698,415
  • 94
  • 811
  • 1,216
  • 1
    Have you looked at the inline documentation? It's very verbose: https://github.com/berkshelf/berkshelf/blob/master/lib/berkshelf/berksfile.rb – sethvargo Jan 13 '14 at 17:18
  • 1
    @sethvargo - I hear what you say. But end users should NOT have to read the source code of the tool chain to find out what the tools do. – Stephen C Jan 19 '14 at 01:10
  • You don't have to. But if you want the *complete* list of declarations you do. It makes no sense to document that outside of the code, and risk having it become stale and outdated. Usage docs != dev docs, and the use case you've described is development documentation IMO – sethvargo Jan 19 '14 at 04:41
  • There's also many differences between Berkshelf 2 and 3. I think this kind of discussion would be much more productive on the project where myself and the other maintainers can provide an actual solution. – sethvargo Jan 19 '14 at 04:41
  • @sethvargo - Would that solution extend to updating the documentation for Berkshelf 2? – Stephen C Jan 19 '14 at 23:33
  • In order to get the 3.0 release out the door, we are not actively working on the 2.x series at this time. – sethvargo Jan 20 '14 at 20:24
  • @sethvargo, the link you posted https://github.com/berkshelf/berkshelf/blob/master/lib/berkshelf/berksfile.rb isn't working – user674669 Jul 16 '18 at 17:39

1 Answers1

2

For my answer, I'm going to link to the v2.0.12 versions of things since v3 is under development right now.

A1. Basic syntax is the same as any Ruby file, since the Berksfile is just yet another Ruby DSL (It seems to be primarily driven by this source, and some help from their DSL Eval Mixin)

A2. Complete list of declarations is hard to define since Ruby can be altered / enhanced in many ways at any time. (Hurray for monkeypatching). But it seems that as of the v2.0.12 the full set of declarations include (metadata,group,site,chef_api,cookbook), as these are the methods marked with expose_method. Options to each of course is up to the implementations of each of the same. (Also any valid ruby is possible to be put into the Berksfile as well I take advantage of this in A3, the evaluation is of course happening inside the CleanRoom class that's part of the mixin).

A3. Again, extensibility makes this difficult, however from a few passes through, it seems like the CookbookSource class defines what are valid options, with some class level methods. Well, taking advantage of that it's a ruby dsl, I threw

puts "options: #{Berkshelf::CookbookSource.valid_options}"

into my Berksfile, ran berks and came out with: 

options: [:constraint, :locations, :group, :locked_version, :chef_api, :node_name, :client_key, :git, :ref, :branch, :tag, :rel, :github, :protocol, :site, :path, :metadata]

Now what all of these mean, will take more diving through the source code. However, maybe this this will give you a starting place to look through things?

Out of curiosity, what documentation do you feel is missing from http://berkshelf.com ?

Charlie
  • 7,181
  • 1
  • 35
  • 49
  • For example, answers to the questions that I currently can only get by reading the source code; e.g. see A1,2,3 above. I'm looking for detailed documentation that someone who is not Ruby developer can understand. Now I realize that Berkshelf allows you to embed arbitrary Ruby on your Berksfile ... but if the user doesn't he should be able to understand how to use Berkshelf without delving to the source code. – Stephen C Jan 13 '14 at 02:59
  • I've actually had the personal experience of learning Berkshelf while trying to learning Ruby and Chef, and found http://berkshelf.com to be in-depth enough. (Actually this evening was my first time going source code to try to figure out how it exactly works, having dealt with Chef's DSLs enough at this point I figured it was something like that). – Charlie Jan 13 '14 at 04:46
  • In fact, with regards to Q3/A3 being the most specific one, it covers all of the options someone would pass. (it doesn't cover constraint, locations, locked_version, and metadata, but these seem to be internal) – Charlie Jan 13 '14 at 04:52
  • I hear what you say. But I'm trying to support people who probably *don't want to* learn another programming language, and certainly wouldn't want to go beyond http://docs.opscode.com/just_enough_ruby_for_chef.html – Stephen C Jan 13 '14 at 08:13
  • 2
    Berksfile can be as simple as you want, just defining `source`, `metadata` to look at your metadata for dependencies, and a list of `cookbooks` and the git path where they live. There's nothing else that you *have* to do, BUT, since it's Ruby, there's so much more than you *can* do with it. – Highway of Life Jan 18 '14 at 00:29