Request: rename tools/* to not conflict with perf-tools

[troyengel]

I package Brendan's perf-tools (https://github.com/brendangregg/perf-tools) and am working on a good package for bcc and it's tools. The tools/* names from Brendan in this project using python+libbcc conflict with the bash-oriented tools with the same name from perf-tools, preventing both packages from cleanly being installed at the same time.

I'd like to request that we rename the tools/* in this project in some fashion so as not to conflict with the other project that's been around for awhile and both are awesome. No preconceived naming convention by me, just looking to resolve the conflict between the two. :)

[drzaeus77]

@brendangregg do you have any suggestions on how to have these cooperate? Should our tools go into a directory under /usr/share/bcc perhaps, or prefix with something?

[brendangregg]

Not sure I understand the original problem. Does this make sense?:

• /usr/share/bcc-tools for bcc/tools
• /usr/share/perf-tools for perf-tools

In the future, I'll be rewriting a lot of the perf-tools in bcc/eBPF anyway.

[drzaeus77]

@troyengel can you point us to the details of where perf-tools is being installed? Concrete examples of what the conflicts are would probably help.

@brendangregg I'm honestly not a linux filesystem hierarchy expert, so it seems okay to me but maybe Troy can weigh in with an opinion as well.

[troyengel]

I think the fundamental question is: as project maintainers, what is the intent of the tools/ subdirectory, are they meant as examples/helpers, or are they meant as ready to use utilities? If it's the former, somewhere in /usr/share/ works but if it's the latter they belong in /usr/bin (or sbin) for use.

Because neither project has a Makefile that actually installs the tools, as AUR (Arch) packaging goes the perf-tools have been around longer, and the package installation is manual to /usr/bin:

• https://aur.archlinux.org/cgit/aur.git/tree/PKGBUILD?h=perf-tools-git

While building the bcc AUR project (it's not checked in to git yet) I wrote the same basic concept, but instead (for now) am putting them in /usr/share/bcc/tools (next to the examples/) to prevent /usr/bin conflicts with perf-tools. This is all based on the assumption to the question posed above "these are ready to use tools". The Red Hat RPM, for instance, just completely ignores the tools/ subdir entirely and they're not in the RPMs.

Right now the basics of the bcc package (I'm planning on compiling both python2 and python3 modules and breaking out subpackages) look like this:

prepare() {
  cd "${srcdir}/${pkgname}-${pkgver}"
  # these two are already fixed in git, 0.1.8 release should have them
  patch -p0 < "${srcdir}/cmake_version-cmake.patch"
  patch -p0 < "${srcdir}/src_python_CMakeLists-txt.patch"
}

build() {
  [[ -d "${srcdir}/${pkgname}-${pkgver}/build" ]] && \
    rm -rf "${srcdir}/${pkgname}-${pkgver}/build"
  mkdir "${srcdir}/${pkgname}-${pkgver}/build"
  cd "${srcdir}/${pkgname}-${pkgver}/build"
  cmake .. -DREVISION=${pkgver} -DPYTHON_CMD="python2" \
    -DCMAKE_INSTALL_PREFIX=/usr \
    -DCMAKE_INSTALL_LIBDIR=/usr/lib
  make -j$(grep -c ^process /proc/cpuinfo)
}

package() {
  cd "${srcdir}/${pkgname}-${pkgver}/build"
  make DESTDIR="${pkgdir}/" install
  # the python build process makes this for python3 only
  rm -rf "${pkgdir}"/usr/lib/python*/site-packages/bcc/__pycache__

  # these conflict with the same names from perf-tools which are bash
  # scripts, we'll put these over in /usr/share for now since they
  # are not binaries
  cp -a "${srcdir}/${pkgname}-${pkgver}/tools" \
    "${pkgdir}/usr/share/${pkgname}/"
  cp -a "${srcdir}/${pkgname}-${pkgver}"/man/man8/* \
    "${pkgdir}/usr/share/${pkgname}/tools/"
}

We can do anything here, and as @brendangregg points out his bigger plan is to migrate everything to bcc/eBPF.

[drzaeus77]

Awesome detail @troyengel , thanks for the insight.

To answer the question at hand, I envision the items in tools/ to be ready-to-use utilities. However, I absolutely don't want to break perf-tools, so for the time being bcc-tools make more sense in /usr/share/bcc, with the caveat that they may move or be deprecated in the future. Users should use them with caution, and a manpage warning or readme in the installed tools/ subdirectory could help.

I see two options to avoid breakage, feel free to critique:

1. When/if perf-tools is rebuilt using bcc, add proper /usr/bin packaging in that project and do nothing with bcc-tools, since the location in /usr/share/bcc/tools is harmless. Add a dependency of perf-tools on bcc.
2. Absorb the new implementation of perf-tools into bcc-tools, and then turn on packaging of /usr/bin in this project. Add a replaces=(perf-tools-git) to bcc-tools.

I think in either case, whatever /usr/bin/* entries end up being created should be a separate subpackage, either the primary one out of perf-tools or a subpackage of bcc.

My selfish preference is for # 2. I believe it would ease somewhat synchronization of features and the API, as well as keeping testing in the same location. But, since @brendangregg is the author of both incarnations of these tools, I will defer to him.

[brendangregg]

I'm a little busy right now, but a quick comment about intent of directories:

• examples: Good examples to learn from, from basic (hello world) to advanced. Focus is on teaching how to code. Code should focus on being readable and simple. Examples don't need to have a practical use (eg, hello world).
• tools: Practical tools for end-users. These need man pages, and example files (use case documentation). Focus is on the end-user experience as a tool (USAGE message, options, intuitive), but not the code itself as an example, which may become complex (argument processing). Tools should also be as few as possible, and maintained.

There's a third category that we don't have examples of yet. Maybe call it the "dump":

• dump: Odds-and-ends: scripts that were useful for something once, and are interesting to keep around to borrow from, but aren't going to be documented/maintained as a tool, nor are they suitable as an example.

[drzaeus77]

Erring on the side of caution, I will plan to commit a change to add tools/* into /usr/share/bcc for the time being. Please advise if this is being overly cautious.

[4ast]

+1 for /usr/share/bcc/tools/

[troyengel]

+1 here as well, works for me

[brendangregg]

+1, can always move some later on to /usr/bin