Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add usage guidance to README.md #7

Merged
merged 4 commits into from
Feb 13, 2019
Merged

Add usage guidance to README.md #7

merged 4 commits into from
Feb 13, 2019

Conversation

thundergolfer
Copy link

This project was quite helpful in supporting dependency shading in Bazel, but when first arriving at the repo the README seemed quite unapproachable and unloved.

I've attempted to add usage instruction right on the README.md that are hopefully accurate and useful but they're just what I produced from having used this Bazel rule and figuring out how it worked.

There's still a couple of things that I think are unclear.

  • rule com.twitter.scalding.** foo.@1 this syntax is undocumented. Can you do scalding.* or @2, instead of what's shown in example?
  • jar_jar.rules is plural, but it accepts a string. Can it also accept a list? It would be nice if this info was front and centre.

If I look into the source I could submit an update to this PR that adds more detail.

Copy link
Collaborator

@johnynek johnynek left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great. Thank you for the help.

Maybe we should also link to the jar jar manual which might help people find more complex examples? Does that manual exist? :)

@johnynek johnynek merged commit 29e96c8 into bazeltools:master Feb 13, 2019
@thundergolfer
Copy link
Author

Thank you for the help.

Thank you for being a huge reason Bazel + Scala is a viable combo.

Does that manual exist? :)

I couldn't find it easily.

@johnynek
Copy link
Collaborator

johnynek commented Feb 14, 2019

Kind of you to say!

https://code.google.com/archive/p/jarjar/wikis/CommandLineDocs.wiki

looks like it says:

Rules file format

The rules file is a text file, one rule per line. Leading and trailing whitespace is ignored. There are three types of rules:

rule <pattern> <result>
zap <pattern> 
keep <pattern>

The standard rule (rule) is used to rename classes. All references to the renamed classes will also be updated. If a class name is matched by more than one rule, only the first one will apply.

<pattern> is a class name with optional wildcards. ** will match against any valid class name substring. To match a single package component (by excluding . from the match), a single * may be used instead.

<result> is a class name which can optionally reference the substrings matched by the wildcards. A numbered reference is available for every * or ** in the , starting from left to right: @1, @2, etc. A special @0 reference contains the entire matched class name.

The zap rule causes any matched class to be removed from the resulting jar file. All zap rules are processed before renaming rules.

The keep rule marks all matched classes as "roots". If any keep rules are defined all classes which are not reachable from the roots via dependency analysis are discarded when writing the output jar. This is the last step in the process, after renaming and zapping.

=========

maybe we should just copy that to the README. What do you think?

@thundergolfer
Copy link
Author

Yeah in the context of this project linking someone to CommandLineDocs.wiki is a little misleading.

I'll put a PR up today.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

3 participants