os.findheader support relative headerdirs

[mercury233]

What does this PR do?

Let os.findheader can support searching relative paths.
Some libraries, by default, install header files within folders. For example, the header files for libfreetype-dev are located in:
/usr/include/freetype2/freetype/*.h
/usr/include/freetype2/ft2build.h

Previously, if a program included the header with #include <ft2build.h>, you had to use:
os.findheader("freetype2/ft2build.h") .. "freetype2"
to locate it.

Now you can simply use:
os.findheader("ft2build.h", "freetype2")
to achieve the same result.

How does this PR change Premake's behavior?

Nothing.

Anything else we should know?

Nothing.

Did you check all the boxes?

• Focus on a single fix or feature; remove any unrelated formatting or code changes
• Add unit tests showing fix or feature works; all tests pass
• Mention any related issues (put closes #XXXX in comment to auto-close issue when PR is merged)
• Follow our coding conventions
• Minimize the number of commits
• Align documentation to your changes

You can now support Premake on our OpenCollective. Your contributions help us spend more time responding to requests like these!

[nickclark2016]

Suggestion: "The paths may be absolute or relative. If the path is a relative path, it is relative to each of the default search paths."

[Jarod42]

I think "append" should be use instead of "prepend", to keep original order

[Jarod42]

Same here

[mercury233]

I think the search should prioritize subdirectories. For example, if a user's computer has both /usr/include/lua.h and /usr/include/lua5.1/lua.h, and the user calls os.findheader("lua.h", "lua5.1"), they are more likely looking for the latter.

[Jarod42]

In addition you iterate and modify paths, so os.findheader('lib.h', {'dir1', dir2}) will result in something like
{'/usr/dir1/dir2', '/usr/include/dir2', '/usr/dir1', '/usr/include'}

A table.transform(userpaths to transform relative paths into a table, and keep absolute path as-is would be better, then flatten userpaths, and finally paths = table.join(userpaths, paths)

[Jarod42]

How does this PR change Premake's behavior?

Nothing.

In fact behavior changes

os.findheader("header.h", "./submodules/library")

would no longer search from local directory.

Maybe creating another API would be cleaner, something like

function os.findheaderleaf(name, userpaths)
  local res = os.findheaderleaf(name, userpaths)
  if res then
    path.join(res, path.getdirectory(name))
  else
    return nil
  end
end

[nickclark2016]

@mercury233 - I'm currently prepping for the next (and final) beta release. Do you have any plans to revive this PR? If not, I will close it (feel free to reopen in the future if you desire)

[mercury233]

@nickclark2016 what do you think about creating another API like Jarod42 said?

[nickclark2016]

I would approve a new API