The addition of a /libraries folder (like /modules and /themes) for the purpose of contrib. and project specific custom modules to place shareable javascript or css libraries that should not be included in a module or theme repos due to licensing restrictions and policies of Drupal; is necessary.
In light of 3rd party libraries and content on Drupal.org module and theme developers need a location to instruct Site Builders to download and install said library to.
README should contain:
- why this is folder is here
- notes/links on use of *.libraries.yml file in module/theme to access said library.
- For modules: and installation process points with hook_install (*.install file) and use of hook_requirements($phase) to check the 'install' phase -- demo code
- extended use with Libraries API 3.x -- hook_library_info()
Comment | File | Size | Author |
---|---|---|---|
#93 | 667058-nr-bot.txt | 209 bytes | needs-review-queue-bot |
#85 | #85-add composer install-path and *.libraries.yml use notes.patch | 664 bytes | SKAUGHT |
Comments
Comment #1
Dave ReidAdding 'libraries' tag.
Comment #2
stri_berry CreditAttribution: stri_berry commentedMy normal installation routine before installing drupal 6 was to create
sites/all/modules
sites/all/themes
sites/all/libraries
I see in drupal 7 alpha (6 I think) that you've added 2 of these folders, which is fantastic.
sites/all/modules
sites/all/themes
So I second this suggestion, please also add
sites/all/libraries
Comment #3
gregglesSeems reasonable to me. What do we need, a README.txt to commit into that directory?
Comment #4
Dave ReidYep that should be it. Anyone feel like drafting a basic README.txt now?
Comment #5
travelerttHere is a first draft of the README.txt file that could be put into the sites/all/libraries folder.
Please get sites/all/libraries into core, it's a pain to always have to add that little folder into every installation when it is used so universally. Hey, it couldn't hurt.
Comment #6
jbrown CreditAttribution: jbrown commentedWe don't use // $Id$ anymore.
Comment #7
travelerttOK, Line 1 is removed.
Comment #8
travelerttComment #9
Tor Arne Thune CreditAttribution: Tor Arne Thune commentedLooks good to me. I too create sites/all/libraries every time, so this definitely gets my support. Can't see any downsides.
Comment #10
lyricnz CreditAttribution: lyricnz commentedDoes core have any support for sites/all/libraries? No. hook_library() *could* use that directory, but doesn't.
This directory is a feature of a contributed module (libraries) - so I don't think core should be creating this directory.
Unless... Libraries module is included in core, which I would totally support :)
Comment #11
aspilicious CreditAttribution: aspilicious commentedLyricnz is right... Changing title...
I couldn't find any issue dealing with this. Currently contrib does whatevar it wants with external libraries. In D7 we have hook_library but that is not enough.
- Contrib uses the libraries api
- Contrib doesn't use the api but places the files in the libraries folder
- Contrib just put the library in the module. (mostly it also includes ancient jquery files and stuff)
I think it's a good idea to bring libraries api to core (or a subset of it) so people can use a standard way to handle these external dependencies.
EDIT:
If this is not going to happen we can discuss the original issue.
Comment #12
sunNot sure whether this makes sense. Note that Libraries API supports
libraries
folders in-
sites/all/libraries
,sites/default/libraries
,sites/<site>/libraries
-
profiles/<profile>/libraries
(for installation profiles)-
/libraries
(for distributions)As far as the actual Libraries API functionality is concerned, I'm rather opposed to it - there are still too many unknown and unresolved aspects. The only reason "it works" right now is that we "just hope" no one is running into the multidimensional problems.
Note: Please keep core's built-in hook_library() support out of this discussion. It's totally different.
Comment #13
Anonymous (not verified) CreditAttribution: Anonymous commentedPlease shorten it to lib instead of libraries.
Comment #14
DamienMcKennaivanjaros: The full "libraries" word matches the use of the full words "modules" and "themes", so shouldn't be changed.
I think rather than just saying "add the module" how about defining a set of functionality, which the current module may or may not already include, and we add that step by step?
Comment #15
RobLoachLibraries API is meant to be version agnostic. Drupal Core depends on a specific version of a given library to be there, so like sun said, I'm not sure this is the direction we want to go.
Let's move that discussion over to #1431804: Bikeshed 'lib' vs. 'libraries' directory.
Comment #16
kenorb CreditAttribution: kenorb commentedRelated:
http://drupal.stackexchange.com/questions/26984/alternative-to-libraries...
Comment #17
klonos...I guess this is D9 material now :/
Comment #18
cweagansI'm not so sure about that. I agree with sun that the libraries api might need a bit more time to mature in contrib, but the original proposal (to just add a directory and a readme) is still totally on the table. Whether or not core has direct support for it (where support is checking to make sure that a library is present, that it's the correct version, etc) is not, in my mind, a question that matters. IMO, anything more advanced than encouraging people to use this directory belongs in contrib for now, but we can certainly lay the groundwork for Libraries API in core now. Getting people to standardize on placing third party libraries in /libraries seems like a very good thing in my book.
Comment #19
DamienMcKennaIIRC there are some other issues trying to decide where 3rd party code should go, this should be postponed until those issues are decided upon (no, I don't have an issue # off-hand).
Comment #20
tstoecklerWhen the core/lib directory was introduced I strongly fought that because of the confusion between 'lib' and 'libraries'. At that time it was decided that, we don't really care and accept that. So this shouldn't be postponed. If we decide on / find a better way of asset / library management then that's good. But until then 'libraries' is the de-facto standard and we might as well help people by introducing this directory by default.
Comment #21
JohnAlbinYeah, the lib vs. libraries thing is annoying. Over in #1663622: Change directory structure for JavaScript files we're dealing with the fact that we can't have a core/libraries directory because core/lib exists already. We're moving the 3rd party, non-PHP vendor "libraries" from core/misc over to core/assets/vendor. And eventually we'll move Drupal-specific stuff from core/misc stuff into an organized structure of: core/assets/js, core/assets/css, core/assets/images, etc.
So they'll likely never be a core/libraries directory. Not sure how that affects this issue since we're talking about downloadable, non-composer PHP and JS and CSS libraries instead of composer-driven PHP libraries, etc. And while "assets" applies to the JS/CSS stuff, it doesn't apply to non-composer PHP libraries.
Comment #22
PanchoHmmm. How do we move forward? Do the Libraries API people have a battle plan?
Otherwise #18 might be a good starter, with the only real alternative to a /libraries folder being a /assets folder. The latter might be interesting because name-wise it doesn't collide with the lib folders. While this would be a change regarding what people were used to in D6 and D7, once grasped, it sounds more like a place for everything, not just full-fledged libraries. This might even be beneficial. We might want to discuss this one further.
As a new feature resp. an API addition, some full-featured or basic Libraries API can be added at a later point, even in a point release.
Note that we'd like to add system stream support for libraries in #1308152: Add stream wrappers to access extension files, but therefore need to know what to support...
Comment #23
mgiffordComment #24
geerlingguy CreditAttribution: geerlingguy commentedSo, I am setting up a new D8 site, and according to the CR Most Drupal core files now live in a "core" subdirectory, it seems the pattern I should use, following the new root directory 'modules' and 'themes' layout, is to create a 'libraries' directory in the root of the D8 project structure.
In D7, I know that I should've created a 'libraries' folder at sites/all/libraries, but it doesn't seem documented anywhere what to do in D8. Could we get some clarification, and maybe also update the change record to at least mention libraries?
Comment #25
mgifford@cweagans patch addresses this issue for contrib. I really don't know why this has waited 2 years. This is the pattern that contrib users will expect in D8. This should also be backported to folks who will still be setting up D7 sites.
Comment #26
tstoecklerFor D7 this makes total sense, but for D8 I'm not so sure. Per #21 Libraries API will probably want to put JS and CSS in a
sites/all/assets
directory and for non-Composer-using people may support asites/all/vendor
or something. All that is still vaporware, though. So for D8 this issue can only reasonably be "postponed". Whereas in D7 this is totally valid, so I suggest retargeting it for now.Comment #27
alexpottPHP libraries are not going to go in here. This is what composer or composer manager is for.
I agree with @tstoeckler this issue needs more discussion for Drupal 8.
Comment #28
gregglesMaking a patch with the contents of the last README.txt from #7 by travelrtt.
Updating the title and tags to indicate that this is only about D7 and needs no commits on 8.x.
Comment #29
gregglesand this.
Comment #30
gregglesComment #31
geerlingguy CreditAttribution: geerlingguy commentedWarning: bikeshed...
Can we just remove the "This will allow you to more easily install Drupal contributed modules." line? Seems like the first sentence covers what's needed here... less is more?
Comment #32
mgiffordApplied this to D7 and got the following "warning: 3 lines add whitespace errors."
That's not a big deal at all, but did wonder if there's any chance that adding this to a release of D7 may mess up existing installs. The way we deal with upgrades it shouldn't be a problem, but...
Comment #33
DamienMcKennaI wrapped the lines at 80 chars, per the coding standards. I also removed the second sentence as it's a little redundant, per geerlingguy's comment.
Comment #34
geerlingguy CreditAttribution: geerlingguy commentedI like it. UX win++
Comment #35
tstoecklerAwesome! The usability win gained by this is non-negligible. A lot of Drupal beginners place external libraries into
sites/all/modules/libraries
(vs.sites/all/libraries
) by accident and this will help to alleviate that.RTBC++
Comment #36
David_Rothstein CreditAttribution: David_Rothstein commentedCommitted to 7.x - thanks!
Made some changes on commit though:
- Included an example (borrowed from @cweagans's earlier patch) as I don't think this would have made sense to many people without that.
- Mentioned custom modules too; it's still best practice to use sites/all/libraries for a library your custom module requires.
Note that I also fixed the whitespace errors (bad line endings) on commit.
I suspect we might want more documentation here someday (similar to what sites/all/modules and sites/all/themes have) but this looks like a very good start.
Comment #38
David_Rothstein CreditAttribution: David_Rothstein commentedActually based on #26 and #27 it sounds like this should be open for Drupal 8 still, but postponed.
Comment #39
TwoDNice, but s/Javascript/JavaScript/, please? ;)
Comment #40
David_Rothstein CreditAttribution: David_Rothstein as a volunteer commentedOops, good catch. Went ahead and fixed that now via a direct commit (and gave you credit). Didn't think it was worth uploading a patch or creating a followup issue for a tiny change like that :)
Comment #42
mbrett5062 CreditAttribution: mbrett5062 commentedI see no reason for this to be postponed anymore. If it is in 7.x then it would be a pita for it to disappear in 8.0.x
The libraries module can easily add /libraries as a search path, and it would help with consistency moving forward from 7.x
Comment #43
mgiffordComment #44
darol100 CreditAttribution: darol100 as a volunteer and commentedI thought this was committed already and I just notice it is not. Here is a patch, which contain same README.txt from D7.
Comment #45
mgiffordLooks good to me. This shouldn't cause a problem for upgrades.
Comment #46
tstoecklerSee #26 for why I don't think this makes sense for D8. I think we should just mark this fixed.
Comment #47
darol100 CreditAttribution: darol100 as a volunteer and commented@tstoeckler, This question was ask in the libraries api issue queue (#2511300: drupal 8 libraries location), and the response was pointing to a Drupal Answer where it said that the new libraries folder is at /libraries. In addition, there are contrib projects (like https://www.drupal.org/project/codesnippet) that already are using the libraries directory as central place to added external libraries.
This been said, I think this patch still applies.
Comment #48
catchThis needs an issue summary update. The folder doesn't make any sense unless you have a module that uses it, in which case the module tells you where to put things anyway. Just having the folder by itself seems like it could be confusing.
Comment #49
lpalgarvio CreditAttribution: lpalgarvio commentedComment #50
SKAUGHTComment #51
SKAUGHTComment #52
geerlingguy CreditAttribution: geerlingguy commentedPlease see the following w/r/t issue statuses:
Critical is reserved for bugs and tasks which are extremely urgent/break things; feature requests can go to a maximum of 'Major', but I think this is still a 'Normal' as it's not really impeding any development, more of a nice to have.
Comment #53
SKAUGHTsorry, i break protocols from time to time. nonetheless, this is a critial issue. we (the community) need a spot for this.
otherwise, i'm not sure why this is so stalled. this patch applies fine. lets get this in!
Comment #54
SKAUGHTComment #55
SKAUGHTComment #56
SKAUGHTComment #57
andypostSummary still needs update and probably change record needed, cos a lot of deploy scripts will be affected by existing folder
Comment #58
SKAUGHTComment #59
SKAUGHT@andypost
I've updated summary as best I understand to do. cheers. tagging for change record
Comment #60
catchThat still doesn't explain why we'd add this to core when only a subset of contrib modules use it, and those contrib modules currently include instructions on creating the folder. Also #26 hasn't been answered.
Comment #61
darol100 CreditAttribution: darol100 as a volunteer and commented@catch
I have answer question #26. See #47.
The only reason we should create the
/libraries
folder is to encourage users to use a central place to add their libraries so they can be reused for other modules if is need it. Instead of shipping libraries inside of the modules.Here is a list of other modules that use
/libraries
folder.Comment #62
SKAUGHT@catch
Please, if you take a look at the 'related and referenced by' sidebar you can see The Why.
Drupal policy 3rd party libraries and content on Drupal.org. Projects are breaking this (sorry, at least bending) this policy. Having the folder (and it's README) is the first step for subsequent drupal.org documentation to be created.
Specifically in lue of #2605130: Missing best practices for handling external libraries in Drupal 8 -- we need to establish this practice. General consensus is to use /libraries.
It is because the community has already started doing this. in addtion to darol100's list many other modules that are doing this. And yes, others still instructing people to make a 'sites/all/libraries' --> because D7 has this folder and encourages use. Core needs to clarify this for D8.
The Libraries API should certainly be core in order to provide clear practice for module and theme developers to meet policies about including libraries, and to make those libraries sharable. I certainly hope 8.2 will include it, in the meantime we need to establish and encourage this general practice. This is why core needs this folder.
WHY: because i am a module developer who is trying to port a module for D8 and there's a big black whole about this folder. As such, i agree with the placement of these libraries in DRUPAL_ROOT/libraries.
Comment #63
SKAUGHTComment #64
SKAUGHT(hopefully my last follow up)
libraries API 8.x-3.x README.txt ln 21 has conformed to DRUPAL_ROOT/libraries
Comment #65
tstoecklerRe #64: That is just because 8.x-3.x was branched from 7.x-2.x and the README was never updated.
#21 and #26 still stands, so this is still either won't fix or postponed from my point of view.
Comment #66
star-szrTo me this is badly in need of an issue summary stating why this change is "needed" and why it's a contrib blocker. It's also not accurately titled because it's adding a README.txt, not an empty folder (not possible with git anyway). These may seem like small details but for an issue to be considered for commit they are very important.
Without that information my opinion is it feels off to add this to core if no code in core is reading from it and it's not something with an RFC/standard outside of Drupal like robots.txt, .htaccess, etc.
I would also say that if we truly want this to be helpful we need to include more details in the README. Unless I'm mistaken each library should be in its own folder, at least that seemed to be the convention when working with D7 modules that leveraged the Libraries API module.
The fact that on top of everything else the primary maintainer of the Libraries API module is against this makes it pretty clear cut to me, this is not ready to go in.
Comment #67
darol100 CreditAttribution: darol100 as a volunteer and commentedShould this issue #2605130: Best practices for handling external libraries in Drupal 8/9 and 10 be part of the Libraries API instead of Drupal Core then ? If standards of external libraries is going to be define by the Libraries API.
Comment #68
David_Rothstein CreditAttribution: David_Rothstein as a volunteer commentedI think the quotes around "empty" were meant to indicate that it's not literally an empty folder, but this should make it more clear :)
Comment #69
David_Rothstein CreditAttribution: David_Rothstein as a volunteer commentedAlso if this is postponed we should be clear which issue it's postponed on - is it #2605130: Best practices for handling external libraries in Drupal 8/9 and 10? (Originally I think it was postponed more generally because Drupal 8 wasn't released yet and the folder organization was still in flux, but that's no longer the case.)
I don't see this issue as being specifically related to Libraries API by the way. This is more like: You decide to download a JavaScript library for your site, either for custom usage or because a module told you to... now where in the codebase do you put that JavaScript? There should be some standard answer core can provide here.
I think one reason I committed it to Drupal 7 with a rather sparse README.txt (despite also thinking that could stand to be expanded; see #36) was to avoid being overly prescriptive; the best practices here aren't 100% set it stone, so the idea was for core to recommend something and nudge people towards it, but not to get too much in the way if a contrib module wanted to recommend something different...
Comment #70
David_Rothstein CreditAttribution: David_Rothstein as a volunteer commentedI think @tstoeckler’s comment in #35 is one good reason.
Comment #71
SKAUGHT@tstoeckler
@Cottser
sorry, what. clearly this is where the libraries API, and module developers, is at now. The posts from more than a year ago in this thread shouldn't be a reason to delay.
for sure, not postponing this issue.
@David_Rothstein
I've been poking through the d7 repo and was looking some more at /core/misc folder, and have come across the fact that some cleanup has occurred Change directory structure for JavaScript files. As i was about to add an issue to cleanup misc folder. Without surprise, others have been cleaning up -- a general best practice is needed to be established. even though this was 'voted' on, its not clear why /assets/vendor was chosen (nested folders). I can only see the we have a strange separation due to Composer, but then Core should simplify it to /libraries as its own best practice (ie: /module and /core/module are still just Modules.)
Comment #72
star-szr@SKAUGHT - what I was saying is that from my perspective @tstoeckler (Libraries API module maintainer) in #65 has confirmed that those "old" comments are still applicable today, albeit perhaps indirectly. Perhaps @tstoeckler can restate the reason(s) from his perspective that this should be won't fix or postponed for D8 if that would help clear the air. However, based on the current state of this issue (particularly the issue summary) I'm not seeing any strong argument(s) for adding the folder. So to me any other steps at this point feel premature without a clear "why". Once we have that I think we can have a more productive discussion about this.
Comment #73
SKAUGHT@Cottser
i've updated the summary. and will work on the content of the README and get a patch up shortly.
Comment #74
SKAUGHTComment #75
andypostLooks it good time to get commited
Comment #76
andypostdoes not mean to change status
Comment #79
andypostOnly readme fixes are left here
Comment #84
alexpottNote in some ways the argument about whether this should be included in core is not somewhat moot. In the new composer project templates we have:
So we have a type
drupal-library
that gets put in the libraries directory. And Lightening and Thunder (and probably every other distribution) creates a libraries folder during its installation.So this issue really is should we add a README to this folder and what should it say.
Comment #85
SKAUGHTComment #86
SKAUGHTComment #93
needs-review-queue-bot CreditAttribution: needs-review-queue-bot as a volunteer commentedThe Needs Review Queue Bot tested this issue. It either no longer applies to Drupal core, or fails the Drupal core commit checks. Therefore, this issue status is now "Needs work".
Apart from a re-roll or rebase, this issue may need more work to address feedback in the issue or MR comments. To progress an issue, incorporate this feedback as part of the process of updating the issue. This helps other contributors to know what is outstanding.
Consult the Drupal Contributor Guide to find step-by-step guides for working with issues.