From e625a1115854c812aa19e9c32ca1c07363645427 Mon Sep 17 00:00:00 2001 From: Ash258 Date: Sun, 26 Apr 2020 02:25:15 +0200 Subject: [PATCH] chore: Other tweaks - License change - PSScriptAnalyzer - Add bare wiki as MD --- LICENSE | 698 ++++++++++++++++- PSScriptAnalyzerSettings.psd1 | 23 - README.md | 9 +- _wiki/.gitkeep | 1 - _wiki/concepts/App-Manifest-Autoupdate.md | 704 ++++++++++++++++++ _wiki/concepts/App-Manifests.md | 84 +++ _wiki/concepts/Apps.md | 7 + _wiki/concepts/Buckets.md | 80 ++ _wiki/concepts/Creating-an-app-manifest.md | 42 ++ _wiki/concepts/Dependencies.md | 44 ++ _wiki/concepts/Persistent-data.md | 44 ++ .../concepts/Pre--and-Post-install-scripts.md | 35 + _wiki/concepts/The-Current-Version-Alias.md | 42 ++ _wiki/getting-started/Commands.md | 44 ++ _wiki/getting-started/FAQ.md | 37 + _wiki/getting-started/Quick-Start.md | 121 +++ _wiki/getting-started/Uninstalling-Scoop.md | 19 + _wiki/guides/Apache-with-PHP.md | 59 ++ _wiki/guides/Custom-PHP-configuration.md | 52 ++ _wiki/guides/Docker.md | 62 ++ _wiki/guides/Github-with-SSH-key.md | 64 ++ _wiki/guides/Java.md | 126 ++++ _wiki/guides/SSH-on-Windows.md | 126 ++++ _wiki/guides/Theming-Powershell.md | 38 + .../Antivirus-and-Anti-Malware-Problems.md | 20 + _wiki/misc/Can-I-Use-Scoop-in-Bash.md | 19 + ...a-for-including-apps-in-the-main-bucket.md | 9 + _wiki/misc/Example-Setup-Scripts.md | 53 ++ _wiki/misc/Global-Installs.md | 33 + .../Multi-connection-downloads-with-aria2.md | 15 + _wiki/misc/PowerShell-Modules.md | 23 + .../Switching-Ruby-and-Python-Versions.md | 45 ++ _wiki/misc/Using-Scoop-behind-a-proxy.md | 84 +++ _wiki/misc/Why-PowerShell.md | 30 + _wiki/overview/Chocolatey-Comparison.md | 13 + _wiki/overview/Cygwin-and-MSYS-Comparison.md | 20 + _wiki/overview/So-What.md | 41 + 37 files changed, 2912 insertions(+), 54 deletions(-) delete mode 100644 _wiki/.gitkeep create mode 100644 _wiki/concepts/App-Manifest-Autoupdate.md create mode 100644 _wiki/concepts/App-Manifests.md create mode 100644 _wiki/concepts/Apps.md create mode 100644 _wiki/concepts/Buckets.md create mode 100644 _wiki/concepts/Creating-an-app-manifest.md create mode 100644 _wiki/concepts/Dependencies.md create mode 100644 _wiki/concepts/Persistent-data.md create mode 100644 _wiki/concepts/Pre--and-Post-install-scripts.md create mode 100644 _wiki/concepts/The-Current-Version-Alias.md create mode 100644 _wiki/getting-started/Commands.md create mode 100644 _wiki/getting-started/FAQ.md create mode 100644 _wiki/getting-started/Quick-Start.md create mode 100644 _wiki/getting-started/Uninstalling-Scoop.md create mode 100644 _wiki/guides/Apache-with-PHP.md create mode 100644 _wiki/guides/Custom-PHP-configuration.md create mode 100644 _wiki/guides/Docker.md create mode 100644 _wiki/guides/Github-with-SSH-key.md create mode 100644 _wiki/guides/Java.md create mode 100644 _wiki/guides/SSH-on-Windows.md create mode 100644 _wiki/guides/Theming-Powershell.md create mode 100644 _wiki/misc/Antivirus-and-Anti-Malware-Problems.md create mode 100644 _wiki/misc/Can-I-Use-Scoop-in-Bash.md create mode 100644 _wiki/misc/Criteria-for-including-apps-in-the-main-bucket.md create mode 100644 _wiki/misc/Example-Setup-Scripts.md create mode 100644 _wiki/misc/Global-Installs.md create mode 100644 _wiki/misc/Multi-connection-downloads-with-aria2.md create mode 100644 _wiki/misc/PowerShell-Modules.md create mode 100644 _wiki/misc/Switching-Ruby-and-Python-Versions.md create mode 100644 _wiki/misc/Using-Scoop-behind-a-proxy.md create mode 100644 _wiki/misc/Why-PowerShell.md create mode 100644 _wiki/overview/Chocolatey-Comparison.md create mode 100644 _wiki/overview/Cygwin-and-MSYS-Comparison.md create mode 100644 _wiki/overview/So-What.md diff --git a/LICENSE b/LICENSE index 68a49daad8..f288702d2f 100644 --- a/LICENSE +++ b/LICENSE @@ -1,24 +1,674 @@ -This is free and unencumbered software released into the public domain. - -Anyone is free to copy, modify, publish, use, compile, sell, or -distribute this software, either in source code form or as a compiled -binary, for any purpose, commercial or non-commercial, and by any -means. - -In jurisdictions that recognize copyright laws, the author or authors -of this software dedicate any and all copyright interest in the -software to the public domain. We make this dedication for the benefit -of the public at large and to the detriment of our heirs and -successors. We intend this dedication to be an overt act of -relinquishment in perpetuity of all present and future rights to this -software under copyright law. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, -EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. -IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR -OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, -ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR -OTHER DEALINGS IN THE SOFTWARE. - -For more information, please refer to + GNU GENERAL PUBLIC LICENSE + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + Preamble + + The GNU General Public License is a free, copyleft license for +software and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + + TERMS AND CONDITIONS + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public License. + + "Copyright" also means copyright-like laws that apply to other kinds of +works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this +License. Each licensee is addressed as "you". "Licensees" and +"recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of an +exact copy. The resulting work is called a "modified version" of the +earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work based +on the Program. + + To "propagate" a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + + To "convey" a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user through +a computer network, with no transfer of a copy, is not conveying. + + An interactive user interface displays "Appropriate Legal Notices" +to the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work +for making modifications to it. "Object code" means any non-source +form of a work. + + A "Standard Interface" means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + + The "System Libraries" of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +"Major Component", in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + + The Corresponding Source need not include anything that users +can regenerate automatically from other parts of the Corresponding +Source. + + The Corresponding Source for a work in source code form is that +same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + + You may make, run and propagate covered works that you do not +convey, without conditions so long as your license otherwise remains +in force. You may convey covered works to others for the sole purpose +of having them make modifications exclusively for you, or provide you +with facilities for running those works, provided that you comply with +the terms of this License in conveying all material for which you do +not control copyright. Those thus making or running the covered works +for you must do so exclusively on your behalf, under your direction +and control, on terms that prohibit them from making any copies of +your copyrighted material outside their relationship with you. + + Conveying under any other circumstances is permitted solely under +the conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + + When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such circumvention +is effected by exercising rights under this License with respect to +the covered work, and you disclaim any intention to limit operation or +modification of the work as a means of enforcing, against the work's +users, your or third parties' legal rights to forbid circumvention of +technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these conditions: + + a) The work must carry prominent notices stating that you modified + it, and giving a relevant date. + + b) The work must carry prominent notices stating that it is + released under this License and any conditions added under section + 7. This requirement modifies the requirement in section 4 to + "keep intact all notices". + + c) You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable section 7 + additional terms, to the whole of the work, and all its parts, + regardless of how they are packaged. This License gives no + permission to license the work in any other way, but it does not + invalidate such permission if you have separately received it. + + d) If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has interactive + interfaces that do not display Appropriate Legal Notices, your + work need not make them do so. + + A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +"aggregate" if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms +of sections 4 and 5, provided that you also convey the +machine-readable Corresponding Source under the terms of this License, +in one of these ways: + + a) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b) Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that product + model, to give anyone who possesses the object code either (1) a + copy of the Corresponding Source for all the software in the + product that is covered by this License, on a durable physical + medium customarily used for software interchange, for a price no + more than your reasonable cost of physically performing this + conveying of source, or (2) access to copy the + Corresponding Source from a network server at no charge. + + c) Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, and + only if you received the object code with such an offer, in accord + with subsection 6b. + + d) Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to the + Corresponding Source in the same way through the same place at no + further charge. You need not require recipients to copy the + Corresponding Source along with the object code. If the place to + copy the object code is a network server, the Corresponding Source + may be on a different server (operated by you or a third party) + that supports equivalent copying facilities, provided you maintain + clear directions next to the object code saying where to find the + Corresponding Source. Regardless of what server hosts the + Corresponding Source, you remain obligated to ensure that it is + available for as long as needed to satisfy these requirements. + + e) Convey the object code using peer-to-peer transmission, provided + you inform other peers where the object code and Corresponding + Source of the work are being offered to the general public at no + charge under subsection 6d. + + A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means any +tangible personal property which is normally used for personal, family, +or household purposes, or (2) anything designed or sold for incorporation +into a dwelling. In determining whether a product is a consumer product, +doubtful cases shall be resolved in favor of coverage. For a particular +product received by a particular user, "normally used" refers to a +typical or common use of that class of product, regardless of the status +of the particular user or of the way in which the particular user +actually uses, or expects or is expected to use, the product. A product +is a consumer product regardless of whether the product has substantial +commercial, industrial or non-consumer uses, unless such uses represent +the only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, +procedures, authorization keys, or other information required to install +and execute modified versions of a covered work in that User Product from +a modified version of its Corresponding Source. The information must +suffice to ensure that the continued functioning of the modified object +code is in no case prevented or interfered with solely because +modification has been made. + + If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + + The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or updates +for a work that has been modified or installed by the recipient, or for +the User Product in which it has been modified or installed. Access to a +network may be denied when the modification itself materially and +adversely affects the operation of the network or violates the rules and +protocols for communication across the network. + + Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + + When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders of +that material) supplement the terms of this License with terms: + + a) Disclaiming warranty or limiting liability differently from the + terms of sections 15 and 16 of this License; or + + b) Requiring preservation of specified reasonable legal notices or + author attributions in that material or in the Appropriate Legal + Notices displayed by works containing it; or + + c) Prohibiting misrepresentation of the origin of that material, or + requiring that modified versions of such material be marked in + reasonable ways as different from the original version; or + + d) Limiting the use for publicity purposes of names of licensors or + authors of the material; or + + e) Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f) Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified versions of + it) with contractual assumptions of liability to the recipient, for + any liability that these contractual assumptions directly impose on + those licensors and authors. + + All other non-permissive additional terms are considered "further +restrictions" within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; +the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + + However, if you cease all violation of this License, then your +license from a particular copyright holder is reinstated (a) +provisionally, unless and until the copyright holder explicitly and +finally terminates your license, and (b) permanently, if the copyright +holder fails to notify you of the violation by some reasonable means +prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + + Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or +run a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + + An "entity transaction" is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + + You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's "contributor version". + + A contributor's "essential patent claims" are all patent claims +owned or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, "control" includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + + Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + + In the following three paragraphs, a "patent license" is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To "grant" such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + + If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. "Knowingly relying" means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + + A patent license is "discriminatory" if it does not include within +the scope of its coverage, prohibits the exercise of, or is +conditioned on the non-exercise of one or more of the rights that are +specifically granted under this License. You may not convey a covered +work if you are a party to an arrangement with a third party that is +in the business of distributing software, under which you make payment +to the third party based on the extent of your activity of conveying +the work, and under which the third party grants, to any of the +parties who would receive the covered work from you, a discriminatory +patent license (a) in connection with copies of the covered work +conveyed by you (or copies made from those copies), or (b) primarily +for and in connection with specific products or compilations that +contain the covered work, unless you entered into that arrangement, +or that patent license was granted, prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey a +covered work so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you may +not convey it at all. For example, if you agree to terms that obligate you +to collect a royalty for further conveying from those to whom you convey +the Program, the only way you could satisfy both those terms and this +License would be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new versions of +the GNU General Public License from time to time. Such new versions will +be similar in spirit to the present version, but may differ in detail to +address new problems or concerns. + + Each version is given a distinguishing version number. If the +Program specifies that a certain numbered version of the GNU General +Public License "or any later version" applies to it, you have the +option of following the terms and conditions either of that numbered +version or of any later version published by the Free Software +Foundation. If the Program does not specify a version number of the +GNU General Public License, you may choose any version ever published +by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future +versions of the GNU General Public License can be used, that proxy's +public statement of acceptance of a version permanently authorizes you +to choose that version for the Program. + + Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY +OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, +THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM +IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF +ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS +THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY +GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE +USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF +DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD +PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), +EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF +SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + + END OF TERMS AND CONDITIONS + + How to Apply These Terms to Your New Programs + + If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the "copyright" line and a pointer to where the full notice is found. + + + Copyright (C) + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + This program is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + +Also add information on how to contact you by electronic and paper mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + Copyright (C) + This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type `show c' for details. + +The hypothetical commands `show w' and `show c' should show the appropriate +parts of the General Public License. Of course, your program's commands +might be different; for a GUI interface, you would use an "about box". + + You should also get your employer (if you work as a programmer) or school, +if any, to sign a "copyright disclaimer" for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +. + + The GNU General Public License does not permit incorporating your program +into proprietary programs. If your program is a subroutine library, you +may consider it more useful to permit linking proprietary applications with +the library. If this is what you want to do, use the GNU Lesser General +Public License instead of this License. But first, please read +. diff --git a/PSScriptAnalyzerSettings.psd1 b/PSScriptAnalyzerSettings.psd1 index 4e6ee2f57f..e975ebe04b 100644 --- a/PSScriptAnalyzerSettings.psd1 +++ b/PSScriptAnalyzerSettings.psd1 @@ -1,29 +1,6 @@ -# The PowerShell Script Analyzer will generate a warning -# diagnostic record for this file due to a bug - -# https://github.com/PowerShell/PSScriptAnalyzer/issues/472 @{ - # Only diagnostic records of the specified severity will be generated. - # Uncomment the following line if you only want Errors and Warnings but - # not Information diagnostic records. Severity = @('Error','Warning') - # Analyze **only** the following rules. Use IncludeRules when you want - # to invoke only a small subset of the defualt rules. - # IncludeRules = @('PSAvoidDefaultValueSwitchParameter', - # 'PSMisleadingBacktick', - # 'PSMissingModuleManifestField', - # 'PSReservedCmdletChar', - # 'PSReservedParams', - # 'PSShouldProcess', - # 'PSUseApprovedVerbs', - # 'PSAvoidUsingCmdletAliases', - # 'PSUseDeclaredVarsMoreThanAssignments') - - # Do not analyze the following rules. Use ExcludeRules when you have - # commented out the IncludeRules settings above and want to include all - # the default rules except for those you exclude below. - # Note: if a rule is in both IncludeRules and ExcludeRules, the rule - # will be excluded. ExcludeRules = @( # Currently Scoop widely uses Write-Host to output colored text. 'PSAvoidUsingWriteHost', diff --git a/README.md b/README.md index 1ee7575aa9..41e6282c68 100644 --- a/README.md +++ b/README.md @@ -149,13 +149,10 @@ The following buckets are known to scoop: - [versions](https://github.com/ScoopInstaller/Versions) - Alternative versions of apps found in other buckets The main bucket is installed by default. To add any of the other buckets, type: -``` -scoop bucket add bucketname -``` +`scoop bucket add bucketname` + For example, to add the extras bucket, type: -``` -scoop bucket add extras -``` +`scoop bucket add extras` ## Other application buckets diff --git a/_wiki/.gitkeep b/_wiki/.gitkeep deleted file mode 100644 index 5606510269..0000000000 --- a/_wiki/.gitkeep +++ /dev/null @@ -1 +0,0 @@ -Comfort CI diff --git a/_wiki/concepts/App-Manifest-Autoupdate.md b/_wiki/concepts/App-Manifest-Autoupdate.md new file mode 100644 index 0000000000..d20e6709ef --- /dev/null +++ b/_wiki/concepts/App-Manifest-Autoupdate.md @@ -0,0 +1,704 @@ +# Autoupdate + +**Auto Update** is a tool for package maintainers. It automatically checks for new versions of an app and updates the manifest accordingly. It helps to eliminate much of the tedium of updating manifests, as well as reducing the risk of human error while doing so. + +Here you will find an in-depth explanation of how the `autoupdate` part of an app manifest works. + +## Using `checkver.ps1` to query and autoupdate + +Use `checkver.ps1` to query the current version of either a specific app or all apps of a bucket. If an updated version existed, you can autoupdate manifest by `checkver.ps1` too. + +### Querying current version + +Open a PowerShell/CMD console, then `cd` into Scoop's root directory (`apps\scoop\current`) or the buckets repository directory and run the following commands: + +- To query the current version of a specific app in the bucket, run: + + ```powershell + .\bin\checkver.ps1 + # or .\bin\checkver.ps1 -App + ``` + +- To query the current version of all apps in the bucket, run: + + ```powershell + .\bin\checkver.ps1 * + # or .\bin\checkver.ps1 -App * + ``` + +### Updating manifest + +In the output of `checkver.ps1`, you can see if an outdated app has autoupdate available. If so, you can run the following command to automatically update the respective app's manifest (use `*` to update all apps) + +```powershell +.\bin\checkver.ps1 -u +# or .\bin\checkver.ps1 -App -Update +``` + +To query apps that not in `bucket` directory (e.g. `.`, `.\TODO`, etc.), specify the directory as the second argument to `checkver.ps1` + +```powershell +.\bin\checkver.ps1 -u +# or .\bin\checkver.ps1 -App -Dir -Update +``` + +It is recommended to verify that the updated manifest still works by installing the app with the following command + +```powershell +scoop install bucket\.json +``` + +### Parameters of `checkver.ps1` + +- `-App` (`-a APP`) + - Manifest name to search. + - Placeholders (`*`) are supported. +- `-Dir` (`-d DIR`) + - Where to search for manifest(s). +- `-Update` (`-u`) + - Update given manifest. +- `-ForceUpdate` (`-f`) + - Check manifest(s) and update, even if there is no new version. +- `-SkipUpdated` (`-s`) + - Check given manifest(s), and list only outdated manifest(s). +- `-Version` (`-v VER`) + - Check given manifest(s) using a given version `VER`. + - Usually used with `-u` to update to a certain version. + +## Adding `checkver` to a manifest + +### Using RegEx in `checkver` + +Simplest solution is to use an RegEx and it will match it to the source of `homepage`. Example: [go](https://github.com/ScoopInstaller/Main/blob/master/bucket/go.json) + +```json +{ + "homepage": "", + "checkver": "Build version go([\\d\\.]+)\\." +} +``` + +If you're not familiar with RegEx or want to test if your RegEx matches on the right text you can use an online tool ([RegEx101](https://regex101.com/) or [RegExr](https://regexr.com/)). + +Use another url if the `homepage` doesn't contain the version. Example: [7zip](https://github.com/ScoopInstaller/Main/blob/master/bucket/7zip.json) + +```json +{ + "homepage": "https://www.7-zip.org/", + "checkver": { + "url": "https://www.7-zip.org/download.html", + "regex": "Download 7-Zip ([\\d.]+)" + } +} +``` + +### Using JSONPath in `checkver` + +Use a JSON endpoint with [JSONPath expressions](https://goessner.net/articles/JsonPath/) to retrieve the version. Either dot-notation or bracket-notation can be used. Example: [mro](https://github.com/ScoopInstaller/Main/blob/master/bucket/mro.json) + +```json +{ + "checkver": { + "url": "https://mran.microsoft.com/assets/configurations/app.config.json", + "jp": "$.latestMicrosoftRVersion" + } +} +``` + +If you're not familiar with JSONPath or want to test if your JSONPath matches on the right text you can use an online tool ([JSONPath Expression Tester](https://jsonpath.curiousconcept.com/)). + +There could be a JSONPath query in `checkver.jsonpath`, and so does RegEx ([sample reference](https://www.newtonsoft.com/json/help/html/RegexQuery.htm)). Example: [nuget](https://github.com/ScoopInstaller/Main/blob/master/bucket/nuget.json) + +```json +{ + "checkver": { + "url": "https://dist.nuget.org/index.json", + "jp": "$..versions[?(@.displayName == 'nuget.exe - recommended latest')].version" + } +} +``` + +### Using RegEx with JSONPath in `checkver` + +If `checkver.regex` and `checkver.jsonpath` are all assigned, **scoop** use `checkver.jsonpath` to extract a string which `checkver.regex` is matched to to find the version. Example: [nwjs](https://github.com/ScoopInstaller/Main-extras/blob/master/bucket/nwjs.json) + +```json +{ + "checkver": { + "url": "https://nwjs.io/versions.json", + "jsonpath": "$.stable", + "regex": "v([\\d.]+)" + } +} +``` + +### Special Cases + +Use the latest app release on Github by setting `checkver` to `github` and the `homepage` to the repository URL. This will try to match the tag with `\/releases\/tag\/(?:v|V)?([\d.]+)`. _The app author has to use Github's release feature for this to work. Pre-releases will be ignored!_ Example: [nvm](https://github.com/ScoopInstaller/Main/blob/master/bucket/nvm.json) + +```json +{ + "homepage": "https://github.com/coreybutler/nvm-windows", + "checkver": "github" +} +``` + +Or use different urls for the homepage and repository. Example: [cmder](https://github.com/ScoopInstaller/Main/blob/master/bucket/cmder.json) + +```json +{ + "homepage": "http://cmder.net", + "checkver": { + "github": "https://github.com/cmderdev/cmder" + } +} +``` + +Use `checkver.reverse: true` to let `checkver.regex` match the last occurrence found (default is to match the first occurrence). Example: [x264](https://github.com/ScoopInstaller/Main/blob/master/bucket/x264.json) + +```json +{ + "checkver": { + "url": "https://download.videolan.org/pub/videolan/x264/binaries/win64/", + "re": "x264-r(?[\\d]+)-(?[a-fA-F0-9]{7}).exe", + "reverse": true + } +} +``` + +Use capture groups in `checkver.regex` will make [captured variables](#captured-variables) that could be used in `checkver.replace` for complex versions or in [`autoupdate`](#adding-autoupdate-to-a-manifest) property. + +This example will provide `$matchVersion` and `$matchShort` as variables (used in `autoupdate`). Example: [git](https://github.com/ScoopInstaller/Main/blob/master/bucket/git.json) + +```json +{ + "checkver": { + "url": "https://github.com/git-for-windows/git/releases/latest", + "re": "v(?[\\d\\w.]+)/PortableGit-(?[\\d.]+).*\\.exe" + } +} +``` + +This exmple will provide `${1}, ${2}, ${3}` (used in `checkver.replace`) and `$matchSha` (used in `autoupdate`) as variables. Example: [pshazz](https://github.com/ScoopInstaller/Main/blob/master/bucket/pshazz.json) + +```json +{ + "checkver": { + "url": "https://github.com/lukesampson/pshazz/commits/master.atom", + "re": "(\\d+)-(\\d+)-(\\d+)[\\S\\s]*?(?[0-9a-f]{40})", + "replace": "0.${1}.${2}.${3}" + } +} +``` + +### Properties of `checkver` + +- `checkver`: "regex". RegEx for finding the version on the `homepage` + - `github`: "uri". URL to the app's Github repository + - `url`: "uri". Page where the version can be found + - Supports [version variables](#version-variables) + - `regex|re`: "regex". RegEx for finding the version + - `jsonpath|jp`: "jsonpath". JSONPath expression for finding the version + - `xpath`: "string". XPath expression for finding the version + - `reverse`: "boolean". If or not match the last occurrence found + - `replace`: "string". Replace the matched value with a calculated value + - Supports [captured variables](#captured-variables) + - `useragent`: "string". User-Agent that used to get webpage content (only used in [fiddler](https://github.com/lukesampson/scoop-extras/blob/master/bucket/fiddler.json)) + - Supports [version variables](#version-variables) + +## Adding `autoupdate` to a manifest + +For the autoupdate feature to work it needs a [`checkver`](#adding-checkver-to-a-manifest) property +to find the latest version number. + +```json +{ + "autoupdate": { + "note": "Thanks for using autoupdate, please test your updates!", + "architecture": { + "64bit": { + "url": "https://example.org/dl/example-v$version-x64.msi" + }, + "32bit": { + "url": "https://example.org/dl/example-v$version-x86.msi" + } + } + } +} +``` + +Some example manifests using the `autoupdate` feature: + +- [nodejs](https://github.com/ScoopInstaller/Main/blob/master/bucket/nodejs.json) + +```json +{ + "autoupdate": { + "architecture": { + "64bit": { + "url": "https://nodejs.org/dist/v$version/node-v$version-win-x64.7z", + "extract_dir": "node-v$version-win-x64" + }, + "32bit": { + "url": "https://nodejs.org/dist/v$version/node-v$version-win-x86.7z", + "extract_dir": "node-v$version-win-x86" + } + }, + "hash": { + "url": "$baseurl/SHASUMS256.txt.asc" + } + } +} +``` + +- [php](https://github.com/ScoopInstaller/Main/blob/master/bucket/php.json) + +```json +{ + "autoupdate": { + "architecture": { + "64bit": { + "url": "https://windows.php.net/downloads/releases/php-$version-Win32-VC15-x64.zip" + }, + "32bit": { + "url": "https://windows.php.net/downloads/releases/php-$version-Win32-VC15-x86.zip" + } + }, + "hash": { + "url": "$baseurl/sha256sum.txt" + } + } +} +``` + +- [nginx](https://github.com/ScoopInstaller/Main/blob/master/bucket/nginx.json) + +```json +{ + "autoupdate": { + "url": "https://nginx.org/download/nginx-$version.zip", + "extract_dir": "nginx-$version" + } +} +``` + +- [imagemagick](https://github.com/ScoopInstaller/Main/blob/master/bucket/imagemagick.json) + +```json +{ + "autoupdate": { + "architecture": { + "64bit": { + "url": "https://www.imagemagick.org/download/binaries/ImageMagick-$version-portable-Q16-x64.zip" + }, + "32bit": { + "url": "https://www.imagemagick.org/download/binaries/ImageMagick-$version-portable-Q16-x86.zip" + } + }, + "hash": { + "mode": "rdf", + "url": "https://www.imagemagick.org/download/binaries/digest.rdf" + } + } +} +``` + +Some examples using the `autoupdate` feature with [captured variables](#captured-variables) or [version variables](#version-variables): + +- [openjdk](https://github.com/ScoopInstaller/Java/blob/master/openjdk.json) + +```json +{ + "checkver": { + "re": "/(?early_access|GA)/(?jdk(?[\\d.]+)(?:.*)?/(?[\\d]+)(?:/GPL|/binaries)?)/(?openjdk-(?[\\d.]+)(?-ea)?(?:\\+[\\d]+)?_windows-x64_bin.(zip|tar.gz))", + "replace": "${version}-${build}${ea}" + }, + "autoupdate": { + "architecture": { + "64bit": { + "url": "https://download.java.net/java/$matchType/$matchPath/$matchFile" + } + }, + "hash": { + "url": "$url.sha256" + }, + "extract_dir": "jdk-$matchVersion" + } +} +``` + +- [mysql](https://github.com/ScoopInstaller/Main/blob/master/bucket/mysql.json) + +```json +{ + "autoupdate": { + "architecture": { + "64bit": { + "url": "https://dev.mysql.com/get/Downloads/MySQL-$majorVersion.$minorVersion/mysql-$version-winx64.zip", + "extract_dir": "mysql-$version-winx64", + "hash": { + "url": "https://dev.mysql.com/downloads/mysql/", + "find": "md5\">([A-Fa-f\\d]{32})" + } + } + } + } +} +``` + +### Properties of `autoupdate` + +All the properties except `autoupdate.note` can be set globally for all architectures or for each architecture separately (under `architecture.64bit` or `architecture.32bit`). Global properties can be used to update each architectural properties, i.e., if only setted globally, `autoupdate.url` is used to update either `architecture.64bit.url` or `architecture.32bit.url`. + +- `url`: "uri". An URL template for generating the new url + - **scoop** will rename files by appending `#/dl.7z` or `#/pngcrush.exe` to the URL (useful for extracting installers or renaming executables version string) + - Supports [captured variables](#captured-variables) + - Supports [version variables](#version-variables) +- `hash`: "object". Set this [property](#adding-hash-to-autoupdate) for obtaining hash values without download the actual files +- `extract_dir`: "string". Option to update `extract_dir` + - Supports [captured variables](#captured-variables) + - Supports [version variables](#version-variables) +- `note`: "string". Optional message to be displayed when the autoupdate command is run + +## Adding `hash` to `autoupdate` + +There are several ways to obtain the hash of the new file. If the app provider publishes hash values it is possible to extract these from their website or hashfile. If nothing is defined or something goes wrong while getting the hash values the target files will be downloaded and hashed locally. + +Hash value can be directly extracted by the following method (`autoupdate.hash.mode`): + +- Using RegEx for plain text file or webpage (`extract`, _predefined `fosshub`, `sourceforge`_) +- Using JSONPath for JSON file (`json`) +- Using XPath for XML file (`xpath`) +- Using Digest for RDF file (`rdf`) +- Using download header or `.meta4` for [Metalink](http://www.metalinker.org) (`metalink`) + +### Specifying URL in `hash.url` + +`url` in `hash` property accepts URL with [captured variables](#captured-variables), [version variables](#version-variables) or [URL variables](#url-variables). + +- Use [captured variables](#captured-variables). Example: [qemu](https://github.com/ScoopInstaller/Main/blob/master/bucket/qemu.json) + +```json +{ + "checkver": { + "re": "(?\\d{4})-(?\\d{2})-(?\\d{2}): New QEMU installers \\((?[\\d.a-z\\-]+)\\)" + }, + "autoupdate": { + "architecture": { + "64bit": { + "url": "https://qemu.weilnetz.de/w64/qemu-w64-setup-$matchYear$matchMonth$matchDay.exe#/dl.7z", + "hash": { + "url": "https://qemu.weilnetz.de/w64/qemu-w64-setup-$matchYear$matchMonth$matchDay.sha512" + } + }, + "32bit": { + "url": "https://qemu.weilnetz.de/w32/qemu-w32-setup-$matchYear$matchMonth$matchDay.exe#/dl.7z", + "hash": { + "url": "https://qemu.weilnetz.de/w32/qemu-w32-setup-$matchYear$matchMonth$matchDay.sha512" + } + } + } + } +} +``` + +- Use [version variables](#version-variables). Example: [julia](https://github.com/ScoopInstaller/Main/blob/master/julia.json) + +```json +{ + "hash": { + "url": "https://julialang-s3.julialang.org/bin/checksums/julia-$version.sha256" + } +} +``` + +- Use [URL variables](#url-variables) and append suffix to it. Example: [apache](https://github.com/ScoopInstaller/Main/blob/master/apache.json) + +```json +{ + "hash": { + "url": "$url_fossies.sha256" + } +} +``` + +### Getting hash from plain text file or webpage + +If the app provider publishes hash value in a plain text file or on some webpage, `checkver.ps1` could extract it by using proper RegEx. + +#### Using Built-in RegEx in `autoupdate.hash` + +There are some _default_ RegEx that built in **scoop**, i.e., `^([a-fA-F0-9]+)$` and `([a-fA-F0-9]{32,128})[\x20\t]+.*$basename(?:[\x20\t]+\d+)?`. + +```powershell +# ^([a-fA-F0-9]+)$ +abcdef0123456789abcdef0123456789abcdef01 +# ([a-fA-F0-9]{32,128})[\x20\t]+.*`$basename(?:[\x20\t]+\d+)? +abcdef0123456789abcdef0123456789abcdef01 *example.zip +``` + +See [above](#specifying-url-in-hashurl) for examples. + +#### Using customized RegEx in `autoupdate.hash` + +If built-in RegEx is not suitable, customized RegEx could be used to extract hash value. [Hash variables](#hash-variables) (`$md5`, `$sha1`, `$sha256`, and etc.) could be used to simplify the expression. + +- [curl](https://github.com/ScoopInstaller/Main/blob/master/bucket/curl.json) + +```json +{ + "hash": { + "url": "$baseurl/hashes.txt", + "find": "SHA256\\($basename\\)=\\s+([a-fA-F\\d]{64})" + } +} +``` + +- [python](https://github.com/ScoopInstaller/Main/blob/master/bucket/python.json) + +```json +{ + "hash": { + "url": "https://www.python.org/downloads/release/python-$cleanVersion/", + "find": "$basename[\\S\\s]+?$md5" + } +} +``` + +#### Special cases for FossHub and SourceForge + +There are two predefined special cases: [FossHub](https://www.fosshub.com) and [SourceForge](https://sourceforge.net). + +- FossHub + - URL pattern: `^(?:.*fosshub.com\/).*(?:\/|\?dwl=)(?.*)$` + - `https://www.fosshub.com/Calibre.html?dwl=calibre-64bit-3.44.0.msi` + - `https://www.fosshub.com/Calibre.html/calibre-64bit-3.44.0.msi` + - RegEx: `$basename.*?"sha256":"([a-fA-F0-9]{64})"` +- SourceForge + - URL pattern: `(?:downloads\.)?sourceforge.net\/projects?\/(?[^\/]+)\/(?:files\/)?(?.*)` + - `https://downloads.sourceforge.net/project/nsis/NSIS%203/3.04/nsis-3.04.zip` + - `https://sourceforge.net/projects/nsis/files/NSIS%203/3.04/nsis-3.04.zip` + - RegEx: `"$basename":.*?"sha1":\s"([a-fA-F0-9]{40})"` + +For `autoupdate.url`s that match above patterns, hash mode is setted to `fosshub` or `sourceforge` automatically and `hash` property is not needed. + +- [calibre](https://github.com/ScoopInstaller/Main/blob/master/bucket/curl.json) + +```json +{ + "autoupdate": { + "url": "https://www.fosshub.com/Calibre.html/calibre-portable-installer-$version.exe" + } +} +``` + +- [nsis](https://github.com/lukesampson/scoop-extras/blob/master/bucket/nsis.json) + +```json +{ + "autoupdate": { + "url": "https://downloads.sourceforge.net/project/nsis/NSIS%20$majorVersion/$version/nsis-$version.zip", + "extract_dir": "nsis-$version" + } +} +``` + +### Getting hash from JSON file + +For JSON file, use a JSON endpoint with [JSONPath expressions](https://goessner.net/articles/JsonPath/) to retrieve the hash. Either dot-notation or bracket-notation can be used. Example: [openssl](https://github.com/ScoopInstaller/Main/blob/master/bucket/openssl.json) + +```json +{ + "hash": { + "mode": "json", + "jp": "$.files.['$basename'].sha512", + "url": "$baseurl/win32_openssl_hashes.json" + } +} +``` + +There could be a JSONPath query in `autoupdate.hash.jsonpath`, and so does RegEx ([sample reference](https://www.newtonsoft.com/json/help/html/RegexQuery.htm)). Example: [mro](https://github.com/ScoopInstaller/Main/blob/master/bucket/mro.json) + +```json +{ + "hash": { + "mode": "json", + "jsonpath": "$..versions[?(@.downloadText == '$basename')].sha256", + "url": "https://mranapi.azurewebsites.net/api/download" + } +} +``` + +### Getting hash from XML file + +Use XPath to retrieve the hash from a XML file. Example: [googlechrome](https://github.com/h404bi/dorado/blob/master/bucket/googlechrome.json) + +```json +{ + "hash": { + "url": "https://lab.skk.moe/chrome/api/chrome.min.xml", + "xpath": "/chromechecker/stable64[version=\"$version\"]/sha256" + } +} +``` + +### Getting hash from RDF file + +[Resource Description Framework (RDF)](https://www.w3.org/TR/rdf11-concepts/) is a framework for representing information in the Web. Hash value could be extracted from RDF file. Example: [imagemagick](https://github.com/ScoopInstaller/Main/blob/master/bucket/imagemagick.json) + +```json +{ + "hash": { + "mode": "rdf", + "url": "https://www.imagemagick.org/download/binaries/digest.rdf" + } +} +``` + +### Getting hash from from Metalink + +[Metalink](http://www.metalinker.org/) is an Internet standard that harnesses the speed and power of peer to peer networking and traditional downloads with a single click. For download URL that supported Metalink, hash value could be retrieved from download URL's header or a `.meta4` file. Example: [libreoffice-fresh](https://github.com/lukesampson/scoop-extras/blob/master/bucket/libreoffice-fresh.json) + +```json +{ + "hash": { + "mode": "metalink" + } +} +``` + +### Properties of `autoupdate.hash` + +All the properties can be set globally for all architectures or for each architecture separately + +- `mode`: "String | Enum". + - **`extract`**: Extract from a plain text file or webpage by RegEx (Default, can be omitted) + - `json`: Extract from a JSON file by JSONPath + - `xpath`: Extract from a XML file by XPath + - `rdf`: Extract from a RDF file + - `metalink`: Extract from Metalink's header or `.meta4` file + - `fosshub`: _Automatic_. Predefined for FossHub + - `sourceforge`: _Automatic_. Predefined for SourceForge + - `download`: Downloads the app file and hash it locally (Fallback) +- `url`: "Uri". URL template for downloading RDF/JSON files or extracting hashes + - Supports [captured variables](#captured-variables) + - Supports [version variables](#version-variables) + - Supports [URL variables](#url-variables) +- `regex|find`: "Regex". RegEx expression to extract the hash + - Defaults: `^([a-fA-F0-9]+)$` and `([a-fA-F0-9]{32,128})[\x20\t]+.*$basename(?:[\x20\t]+\d+)?` + - Supports [captured variables](#captured-variables) + - Supports [version Variables](#version-variables) + - Supports [URL variables](#url-variables) + - Supports [hash variables](#hash-variables) +- `jsonpath|jp`: "JSONPath". JSONPath expression to extract the hash + - Supports [captured variables](#captured-variables) + - Supports [version Variables](#version-variables) + - Supports [URL variables](#url-variables) +- `xpath`: "String". XPath expression to extract the hash + - Supports [captured variables](#captured-variables) + - Supports [version Variables](#version-variables) + - Supports [URL variables](#url-variables) +- _`type`: "String | Enum". Deprecated. Hash type is determined automatically_ + +## Internal substitutable variables + +### Captured variables + +- Used in `checkver.replace` + - `${1}`, `${2}`, `${3}`...: Unnamed groups + - `${name1}`, `${Name2}`, `${NAME3}`...: Named groups + - `(?...)`, `(?...)`, `(?...)`... +- Used in `autoupdate` + - `$match1`, `$match2`, `$match3`...: Unnamed groups + - `$matchName1`, `$matchName2`, `$matchName3`...: Named groups + - `(?...)`, `(?...)`, `(?...)`... + - _Notice the only uppercase character in variable name_ + +### Version variables + +- `$version`: `3.7.1` +- `$underscoreVersion`: `3_7_1` +- `$dashVersion`: `3-7-1` +- `$cleanVersion`: `371` +- The `$version` (e.g. `3.7.1.2`) is splitted on each `.` and is assigned to: + - `$majorVersion`: `3` + - `$minorVersion`: `7` + - `$patchVersion`: `1` + - `$buildVersion`: `2` +- `$matchHead`: Returns first two or three digits seperated by a dot (e.g. `3.7.1-rc.1` = `3.7.1` , `3.7.1.2-rc.1` = `3.7.1` or `3.7-rc.1` = `3.7`) +- `$matchTail`: Returns the rest of `$matchHead` (e.g. `3.7.1-rc.1` = `-rc.1` , `3.7.1.2-rc.1` = `.2-rc.1` or `3.7-rc.1` = `-rc.1`) +- `$preReleaseVersion`: Everything after the last `-` (e.g. `3.7.1-rc.1` would result in `rc.1`) +- Each capturing group in the [`checkver` property](#adding-checkver-to-a-manifest) adds a `$matchX` variable (named groups are allowed). Matching `v3.7.1/3.7` with [`v(?[\d.]+)\/(?[\d.]+)`](https://regex101.com/r/M7RP3p/1) would result in: + - `$match1` or `$matchVersion`: `3.7.1` + - `$match2` or `$matchShort`: `3.7` + +### URL variables + +- `$url`: autoupdate URL without fragments (`#/dl.7z`) [e.g. `http://example.com/path/file.exe`] +- `$baseurl`: autoupdate URL without filename and fragments (`#/dl.7z`) [e.g. `http://example.com/path`] +- `$basename`: filename from autoupdate URL (ignores fragments `#/dl.7z`) + +### Hash variables + +- `$md5`: `([a-fA-F0-9]{32})` MD5 hash type +- `$sha1`: `([a-fA-F0-9]{40})` SHA-1 hash type +- `$sha256`: `([a-fA-F0-9]{64})` SHA-256 hash type +- `$sha512`: `([a-fA-F0-9]{128})` SHA-512 hash type +- `$checksum`: `([a-fA-F0-9]{32,128})` MD5, SHA-1, SHA-256 or SHA-512 hash type +- `$base64`: `([a-zA-Z0-9+\/=]{24,88})` BASE64 encoded checksum (can be MD5, SHA-1, SHA-256 or SHA-512) + +## Limitations + +There are some complex manifests which reach the limits of the current autoupdate implementation, mainly because `autoupdate` only update `url`, `hash` and `extract_dir`. (_The list of affected manifests is incomplete_) + +- The binaries specified in the `bin` or `shortcuts` change with the version number. Example: [gimp](https://github.com/lukesampson/scoop-extras/blob/master/bucket/gimp.json) +- There are multiple `url`s needed to be updated. Example: [coreutils](https://github.com/ScoopInstaller/Main/blob/master/bucket/coreutils.json) + +## Testing and running autoupdate + +If you want to confirm an autoupdate works, e.g. after adding it to an existing manifest or creating a new one, change the `version` field to a lower or different version and then run `checkver.ps1` or use the `-f` parameter. + +```powershell +cd +scoop config debug $true +.\bin\checkver.ps1 -u +``` + +Check if the `url`, `hash` and `extract_dir` properties have the correct values. Try to install/uninstall the app and submit your changes. + +Manifests in some known buckets are autoupdated by [ScoopInstaller/Excavator](https://github.com/ScoopInstaller/Excavator), so if you want some apps being autoupdated, migrate them to one of these buckets or run an instance of the excavator yourself. + +- [`main`](https://github.com/ScoopInstaller/Main): Update per hour +- [`extras`](https://github.com/lukesampson/scoop-extras): Update per hour +- [`versions`](https://github.com/ScoopInstaller/Versions): Update per day +- [`java`](https://github.com/ScoopInstaller/Java): Update per day +- [`php`](https://github.com/ScoopInstaller/PHP): Update per day +- [`games`](https://github.com/Calinou/scoop-games): Update per day + +## Example Workflow with **scoop** status/update + +`scoop status` compares your installed version against the current copy of **scoop** and bucket repositories on your machine. If these are not updated it will output wrong version information. e.g.: + +- installed version: 2.1.2 +- local **scoop** version: 2.1.3 +- online repo version: 2.1.4 + +`scoop status` will show version 2.1.3 + +Running `scoop update` before `scoop status` is recommended (which is enforced every 3 hours), then it will show currect version 2.1.4. + +`scoop update` just `git pull`s **scoop** core repo to `~\scoop\apps\scoop\current` and every configured bucket to `~\scoop\buckets\` (incl. default main bucket) + +`bin\checkver.ps1` is only for maintenance and updating the manifests so they can be committed to the repo. + +Example Workflow: + +```powershell +cd +.\bin\checkver * -u # updates all manifest in the repo +git commit -m "Updated apps" +git push +scoop update +scoop status +scoop update +``` diff --git a/_wiki/concepts/App-Manifests.md b/_wiki/concepts/App-Manifests.md new file mode 100644 index 0000000000..90af425572 --- /dev/null +++ b/_wiki/concepts/App-Manifests.md @@ -0,0 +1,84 @@ +# App Manifests + +An app manifest is a JSON file that describes how to install a program. + +## A simple example + +```json +{ + "version": "1.0", + "url": "https://github.com/lukesampson/cowsay-psh/archive/master.zip", + "extract_dir": "cowsay-psh-master", + "bin": "cowsay.ps1" +} +``` + +When this manifest is run with `scoop install` it will download the zip file specified by `url`, extract the `cowsay-psh-master` directory from the zip file, and then make the `cowsay.ps1` script available on your path. + +For more examples, see the app manifests in the [main Scoop bucket](https://github.com/ScoopInstaller/Main/tree/master/bucket). + +## Required Properties + +- `version`: The version of the app that this manifest installs, per the [JSON schema definition](https://github.com/lukesampson/scoop/blob/master/schema.json#L526). + +## Optional Properties + +- `##`: A one-line string, or array of strings, containing comments. +- `architecture`: If the app has 32- and 64-bit versions, architecture can be used to wrap the differences ([example](https://github.com/ScoopInstaller/Main/blob/master/bucket/7zip.json)). + - `32bit|64bit`: contains architecture-specific instructions (`bin`, `checkver`, `extract_dir`, `hash`, `installer`, `pre_install`, `post_install`, `shortcuts`, `uninstaller`, `url`, and `msi` [`msi` is deprecated]). +- [`autoupdate`](App-Manifest-Autoupdate.md#adding-autoupdate-to-a-manifest): Definition of how the manifest can be updated automatically. +- `bin`: A string or array of strings of programs (executables or scripts) to make available on the user's path. + - You can also create an alias shim which uses a different name to the real executable and (optionally) passes arguments to the executable. Instead of just using a string for the executable, use e.g: `[ "program.exe", "alias", "--arguments" ]`. See [busybox](https://github.com/ScoopInstaller/Main/blob/master/bucket/busybox.json) for an example. + - However if you declare just one shim like this, you must ensure it's enclosed in an outer array, e.g: + `"bin": [ [ "program.exe", "alias" ] ]`. Otherwise it will be read as separate shims. +- [`checkver`](App-Manifest-Autoupdate.md#adding-checkver-to-a-manifest): App maintainers and developers can use the [`bin/checkver`](https://github.com/lukesampson/scoop/blob/master/bin/checkver.ps1) tool to check for updated versions of apps. The `checkver` property in a manifest is a regular expression that can be used to match the current stable version of an app from the app's homepage. For an example, see the [go](https://github.com/ScoopInstaller/Main/blob/master/bucket/go.json) manifest. If the homepage doesn't have a reliable indication of the current version, you can also specify a different URL to check—for an example see the [ruby](https://github.com/ScoopInstaller/Main/blob/master/bucket/ruby.json) manifest. +- `depends`: Runtime dependencies for the app which will be installed automatically. See also `suggest` (below) for an alternative to `depends`. +- `description`: A one line string containing a short description of the program. Don’t include the name of the program, if it’s the same as the app’s filename. +- `env_add_path`: Add this directory to the user's path (or system path if `--global` is used). The directory is relative to the install directory and must be inside the install directory. +- `env_set`: Sets one or more environment variables for the user (or system if `--global` is used) ([example](https://github.com/ScoopInstaller/Main/blob/master/bucket/go.json)). +- `extract_dir`: If `url` points to a compressed file (.zip, .7z, .tar, .gz, .lzma, and .lzh are supported), Scoop will extract just the directory specified from it. +- `extract_to`: If `url` points to a compressed file (.zip, .7z, .tar, .gz, .lzma, and .lzh are supported), Scoop will extract all content to the directory specified ([example](https://github.com/lukesampson/scoop-extras/blob/master/bucket/irfanview.json)). +- `hash`: A string or array of strings with a file hash for each URL in `url`. Hashes are SHA256 by default, but you can use SHA512, SHA1 or MD5 by prefixing the hash string with 'sha512:', 'sha1:' or 'md5:'. +- `homepage`: The home page for the program. +- `innosetup`: set to the boolean `true` (without quotes) if the installer is InnoSetup based. +- `installer`: Instructions for running a non-MSI installer. + - `file`: The installer executable file. For `installer` this defaults to the last URL downloaded. Must be specified for `uninstaller`. + - `script`: A one-line string, or array of strings, of commands to be executed as an installer/uninstaller instead of `file`. + - `args`: An array of arguments to pass to the installer. Optional. + - `keep`: `"true"` if the installer should be kept after running (for future uninstallation, as an example). If omitted or set to any other value, the installer will be deleted after running. See [`extras/oraclejdk`](https://github.com/lukesampson/scoop-extras/blob/master/oraclejdk.json) for an example. This option will be ignored when used in an `uninstaller` directive. +- `license`: A string or hash of the software license for the program. For well-known licenses, please use the identifier found at https://spdx.org/licenses/ For other licenses, use the URL of the license, if available. Otherwise, use “Freeware”, “Proprietary”, “Public Domain”, “Shareware”, or “Unknown”, as appropriate. If different files have different licenses, separate licenses with a comma (,). If the entire application is [dual licensed](https://en.wikipedia.org/wiki/Multi-licensing), separate licenses with a pipe symbol (|). + - `identifier`: The SPDX identifier, or “Freeware”, “Proprietary”, “Public Domain”, “Shareware”, or “Unknown”, as appropriate. + - `url`: For non-SPDX licenses, include a link to the license. It is acceptable to include links to SPDX licenses, as well. + - If it is difficult to determine all of the different licenses, it is acceptable to add `,...` at the end of the SPDX list. If there are both open-source and not open-source licenses, please list all non-open source licenses first (e.g., Freeware/Proprietary/Shareware). + - If you unable to determine what license the application has, use "Unknown". +- `notes`: A one-line string, or array of strings, with a message to be displayed after installing the app. +- `persist` A string or array of strings of directories and files to persist inside the data directory for the app. See [Persistent data](Persistent-data.md) for more details. +- `post_install`: A one-line string, or array of strings, of the commands to be executed after an application is installed. These can use variables like `$dir`, `$persist_dir`, and `$version`. See [Pre- and post-install Scripts](Pre--and-Post-install-scripts.md) for more details. +- `pre_install`: Same options as `post_install`, but executed before an application is installed. +- `psmodule`: Install as a PowerShell module in `~/scoop/modules`. + - `name` (required for `psmodule`): the name of the module, which should match at least one file in the extracted directory for PowerShell to recognize this as a module. +- `shortcuts`: Specifies the shortcut values to make available in the startmenu. See [sourcetree](https://github.com/lukesampson/scoop-extras/blob/master/bucket/sourcetree.json) for an example. The array has to contain a executable/label pair. The third and fourth element are optional. + 1. Path to target file [required] + 2. Name of the shortcut (supports subdirectories: `\\` [e.g. sysinternals](https://github.com/lukesampson/scoop-extras/blob/master/bucket/sysinternals.json)) [required] + 3. Start parameters [optional] + 4. Path to icon file [optional] +- `suggest`: Display a message suggesting optional apps that provide complementary features. See [ant](https://github.com/ScoopInstaller/Main/blob/master/bucket/ant.json) for an example. \* `["Feature Name"] = [ "app1", "app2"... ]`
e.g. `"JDK": [ "extras/oraclejdk", "openjdk" ]`
+ If any of the apps suggested for the feature are already installed, the feature will be treated as 'fulfilled' and the user won't see any suggestions. +- `uninstaller`: Same options as `installer`, but the file/script is run to uninstall the application. +- `url`: The URL or URLs of files to download. If there's more than one URL, you can use a JSON \* array, e.g. `"url": [ "http://example.org/program.zip", "http://example.org/dependencies.zip" ]`. URLs can be HTTP, HTTPS or FTP. + - To change the filename of the downloaded URL, you can append a URL fragment (starting with `#`) to URLs. For example, + - `"http://example.org/program.exe"` -> `"http://example.org/program.exe#/dl.7z"` + - Note the fragment must start with `#/` for this to work. + - In the above example, Scoop will download `program.exe` but save it as `dl.7z`, which will then be extracted automatically with 7-Zip. This technique is commonly used in Scoop manifests to bypass executable installers which might have undesirable side-effects like registry changes, files placed outside the install directory, or an admin elevation prompt. + +### Undocumented Properties + +- `cookie`: only found [here](https://github.com/se35710/scoop-java/search?q=cookie&unscoped_q=cookie) + +### Deprecated Properties + +- `_comment`: A one-line string, or array of strings, containing comments. Use `##` instead. +- `msi` _(deprecated)_: Settings for running an MSI installer
+ **This property is deprecated and support will be removed in a future version of Scoop.** _The new method is to treat .msi files just like a .zip and extract the files from it without running the full install. You can use the new method simply by not including this `msi` property in your manifest._ + * `code` *required*: the product code GUID for the MSI installer + * `silent`: should normally be `true` to try to install without popups and UAC prompts diff --git a/_wiki/concepts/Apps.md b/_wiki/concepts/Apps.md new file mode 100644 index 0000000000..abfc71aa70 --- /dev/null +++ b/_wiki/concepts/Apps.md @@ -0,0 +1,7 @@ +# Apps + +Scoop uses the term **App** to refer to an application or program to be installed. You might also see it used to loosely refer to a [manifest](App-Manifests.md) that describes how to install an app. + +An app is a self-contained, independent unit. It contains one or more executables or scripts. But that's probably too much of an explanation—generally you'll know an app when you see it. + +Probably the main reason for the term 'app' is that it only takes 3 keystrokes on 2 keys to type. diff --git a/_wiki/concepts/Buckets.md b/_wiki/concepts/Buckets.md new file mode 100644 index 0000000000..06ed873874 --- /dev/null +++ b/_wiki/concepts/Buckets.md @@ -0,0 +1,80 @@ +# Buckets + +## What are buckets? + +In Scoop, buckets are collections of apps. Or, to be more specific, a bucket is a Git repository containing JSON [app manifests](App-Manifests.md) which describe how to install an app. + +Scoop has a [main bucket](https://github.com/ScoopInstaller/Main/tree/master/bucket) which is bundled with Scoop and this is always available as the primary source for installing apps. + +By default, when you run `scoop install `, it looks in the main bucket, but it's possible to install from other buckets too. + +There's an optional [`extras` bucket](https://github.com/lukesampson/scoop-extras) containing apps that don't quite fit the [criteria of the main bucket](../misc/Criteria-for-including-apps-in-the-main-bucket.md), but are still good to have. There is also an optional [`versions`](https://github.com/ScoopInstaller/Versions) bucket containing older versions of some well-known packages. + +And Scoop supports adding other buckets. Anyone can set up their own bucket with their own set of apps, and other people can add and install from this bucket—they just need to know the location of the bucket's Git repository. + +## Known buckets + +There is a list of known buckets by the community, those can be seen in [`buckets.json`](https://github.com/lukesampson/scoop/blob/master/buckets.json), to see the list of known buckets execute: + +```powershell +scoop bucket known +``` + +Many other application buckets hosted on Github can be found in the [Scoop Directory](https://github.com/rasa/scoop-directory). + +## Installing from other buckets + +If you want to install from a bucket besides the main one, you need to configure Scoop to know about the bucket. For example, to add the optional `extras` bucket, run: + +```powershell +scoop bucket add extras +``` + +The 'extras' bucket is a [special bucket](https://github.com/ScoopInstaller/Main/blob/master/buckets.json), in that it's "well known", i.e. Scoop already knows where this bucket is so you don't have to specify its location. + +Just say the extras bucket wasn't well known, the way you'd add it would be: + +```powershell +scoop bucket add extras https://github.com/lukesampson/scoop-extras.git +``` + +That is, + +```powershell +scoop bucket add +``` + +You can run `scoop help bucket` for more information on buckets. + +## Creating your own bucket + +Here's an example of one way you might go about creating a new bucket, using GitHub to host it. You don't have to use GitHub though—you can use whatever source control repo you like, or even just a Git repo on your local or network drive. + +1. Create a new GitHub repo called e.g. `my-bucket` +2. Add an app to your bucket. In a powershell session: + +```powershell +git clone https://github.com//my-bucket +cd my-bucket +'{ version: "1.0", url: "https://gist.github.com/lukesampson/6446238/raw/hello.ps1", bin: "hello.ps1" }' > hello.json +git add . +git commit -m "add hello app" +git push +``` + +3. Configure Scoop to use your new bucket: + +```powershell +scoop bucket add my-bucket https://github.com//my-bucket +``` + +4. Check that it works: + +```powershell +scoop bucket list # -> you should see "my-bucket" +scoop search hello # -> you should see `hello` listed under, "my-bucket bucket:" +scoop install hello +hello # -> you should see "Hello, !" +``` + +5. To share your bucket, all you need to do is tell people how to add your bucket, i.e. by running the command in step 3. If you want your bucket listed in the [Scoop Directory](https://github.com/rasa/scoop-directory) , add a topic of `scoop-bucket` to its github page. diff --git a/_wiki/concepts/Creating-an-app-manifest.md b/_wiki/concepts/Creating-an-app-manifest.md new file mode 100644 index 0000000000..2afee37486 --- /dev/null +++ b/_wiki/concepts/Creating-an-app-manifest.md @@ -0,0 +1,42 @@ +# Creating an App Manifest + +If you want to install a program that's not included in Scoop, it's easy to create an [app manifest](App-Manifests.md) yourself. + +## A basic example + +Here's how to create and install a manifest for an app that says hello, in just a few lines of PowerShell. + +```powershell +# write an app manifest to `hello.json` +'{ "version": "1.0", "url": "https://gist.github.com/lukesampson/6446238/raw/hello.ps1", "bin": "hello.ps1" }' > hello.json + +# install the app +scoop install hello + +# did it work? +hello # -> should output 'Hello, !' +``` + +## Sharing your app + +### Share on your network + +If you want others on your network to be able to install from your app manifest, you could just put it on a network share location, e.g. `/shared/files/scoop/hello.json`. Then, for others to install your app, you can tell them to run: + +```powershell +scoop install /shared/files/scoop/hello.json +``` + +### Share with the world + +If you make your app manifest publicly available on the web, anyone can install it once they know the URL. For example, I've made a GitHub gist for `hello.json` [here](https://gist.github.com/lukesampson/6446567). Now anyone can install it: + +```powershell +scoop install https://gist.github.com/lukesampson/6446567/raw/hello.json +``` + +## Next steps + +If you ran some of these examples, you probably noticed a warning saying "no hash in manifest". For reference information on specifying file hashes and much more in your manifests, see the [App Manifests reference](App-Manifests.md). + +If you want to maintain a collection of apps, see the page on [Buckets](Buckets.md) for more information. diff --git a/_wiki/concepts/Dependencies.md b/_wiki/concepts/Dependencies.md new file mode 100644 index 0000000000..8c241a5b02 --- /dev/null +++ b/_wiki/concepts/Dependencies.md @@ -0,0 +1,44 @@ +# Dependencies + +Scoop treats dependencies in a way you might not expect, especially if you're used to tools like NuGet or Bundler. These tools have to deal with complex problems around long chains of dependencies for specific versions of libraries. Scoop takes a simpler approach. + +### Apps are self-contained units + +They should keep their own copies of any libraries they need to run, and not rely on or interfere with any libraries outside their own install path. + +### It's OK to just install the latest version + +If you were to install Git manually on a new machine, would you go looking for the specific version you had on your last machine to make sure everything works correctly? Or would you just grab the latest version from their website? Scoop assumes you probably want to do the latter. + +If this makes you uncomfortable, remember that unlike software libraries which can have breaking changes between minor version increments, this is less common with programs. + +Of course there are some cases where an old version of a program is still widely used and the new one isn't backwards compatible, like Python versions 2 and 3. Scoop has these cases covered too: you can install the latest 2.7 version with `python27` and for the latest 3.x version it's just `python`. + +## Apps Depending on Other Apps + +Sometimes an app needs another app to install or run properly. For example: + +``` +rust + | + |—— innounp required (to install) + | | + | |—— 7zip required (to install) + | + |—— gcc45 required (to run) + | + |—— 7zip required (to install) +``` + +In this sort of case, when you install an app Scoop will assume you want to install anything required that you don't already have and install these automatically too. + +### Install-time Dependencies vs Runtime Dependencies + +Runtime dependencies are specified with the `depends` setting in the [app manifest](App-Manifests.md). Install-time dependencies are detected based on the file extensions of the `url`s in the app manifest. + +Scoop treats these differently, e.g. `scoop status` only shows warnings for missing **runtime** dependencies. + +## Version dependencies + +- For **software library dependencies**, Scoop just side-steps the problem of version dependencies completely, as described above. +- For **app dependencies** when installing apps, Scoop assumes you want the latest stable version of any dependencies. _Again note that Scoop supports specific versions of apps too, e.g. an app could have a dependency on `python27` (Python v2.7), or `python` (the latest stable version of Python)._ For updating apps, Scoop just does the bare minimum—if a dependency is completely missing it will install it, but if it's on an older version Scoop will leave it alone. diff --git a/_wiki/concepts/Persistent-data.md b/_wiki/concepts/Persistent-data.md new file mode 100644 index 0000000000..4fdca32964 --- /dev/null +++ b/_wiki/concepts/Persistent-data.md @@ -0,0 +1,44 @@ +# Persistent data + +## Data directory + +If you need to store data which should persist between updates you should use `~/scoop/persist//`. +Inside the manifest, the path to the data directory is available in the `$persist_dir` variable. + +The [PHP](https://github.com/ScoopInstaller/Main/blob/master/bucket/php.json) package uses it for the configuration files. + +## App manifest + +Directories and files can be added to the `persist` definition inside the app manifest. +Persist data is linked from the installed application directory to the data directory with directory conjunctions or hard links. + +During the installation, any persistent data is copied into the data directory and linked to. + +### Definition + +The `persist` definition can be string if only one item is needed or an array for multiple items. + +Optionally an item can have a different name inside the data directory: + +```json +{ + "persist": [ + "keeps_its_name", + ["original_name", "new_name_inside_the_data_dir"] + ] +} +``` + +### Examples + +- [MySQL](https://github.com/ScoopInstaller/Main/blob/master/bucket/mysql.json) +- [MariaDB](https://github.com/ScoopInstaller/Main/blob/master/bucket/mariadb.json) +- [Nginx](https://github.com/ScoopInstaller/Main/blob/master/bucket/nginx.json) +- [Node.js](https://github.com/ScoopInstaller/Main/blob/master/bucket/nodejs.json) +- [PHP](https://github.com/ScoopInstaller/Main/blob/master/bucket/php.json) + +## Uninstall + +There is a flag to purge all persist data when you uninstall an app. By default, the data will be kept until you remove it. + + scoop uninstall -p nodejs diff --git a/_wiki/concepts/Pre--and-Post-install-scripts.md b/_wiki/concepts/Pre--and-Post-install-scripts.md new file mode 100644 index 0000000000..d58c087d27 --- /dev/null +++ b/_wiki/concepts/Pre--and-Post-install-scripts.md @@ -0,0 +1,35 @@ +# Pre- and post-install Scripts + +## Variables + +These variables are available for use in `pre_install` / `post_install` scripts: + +| Variable | Example | Description | +| --------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | +| `$dir` | `C:\Users\username\scoop\apps\$app\current` | +| `$original_dir` | `C:\Users\username\scoop\apps\$app\1.2.3` | +| `$persist_dir` | `C:\Users\username\scoop\persist\$app` | +| `$manifest` | `@{homepage=https://example.com/; description=Example app; version=2.4.1; url=http://example.com/app-setup.exe;...` | Deserialized manifest (PowerShell object) | +| `$version` | `1.2.3` | Version being installed | +| `$app` | `exampleapp` | Name of application (name of manifest file) | +| `$architecture` | `64bit` | +| `$scoopdir` | `C:\Users\username\scoop` | Base Scoop install dir | +| `$oldscoopdir` | `C:\Users\username\AppData\Local\scoop` | +| `$globaldir` | `C:\ProgramData\scoop` | +| `$cachedir` | `C:\Users\username\scoop\cache` | +| `$bucketsdir` | `C:\Users\username\scoop\buckets` | +| `$modulesdir` | `C:\Users\username\scoop\modules` | +| `$cfgpath` | `~/.scoop` | Path to Scoop configuration | +| `$cfg` | `{SCOOP_BRANCH, SCOOP_REPO, lastupdate}` | Scoop configuration (PowerShell object) | + +::: tip +Check the [`lib/install`](https://github.com/lukesampson/scoop/blob/master/lib/install.ps1) script for more details. +::: + +## Functions + +### `appdir` + +Reference another scoop application. Eg, to check if another application is installed you can use: + +`"post_install": [ "if (Test-Path \"$(appdir otherapp)\\current\\otherapp.exe\") { <# .. do something .. #> }"` diff --git a/_wiki/concepts/The-Current-Version-Alias.md b/_wiki/concepts/The-Current-Version-Alias.md new file mode 100644 index 0000000000..7f8b7041cc --- /dev/null +++ b/_wiki/concepts/The-Current-Version-Alias.md @@ -0,0 +1,42 @@ +# The "Current" Version Alias + +The `current` directory for apps is a special alias directory which points to the currently installed version of that app. + +It allows path references to remain the same across app updates, since paths refer to the `current` directory alias rather than a hardcoded version directory. + +![How the 'current' alias works](https://raw.githubusercontent.com/lukesampson/scoop/gh-pages/images/Junctions%20Overview.png) + +For example, if I run `ls ~/scoop/apps/git` now, I see this output: + +``` +$ ls ~/scoop/apps/git + + Directory: C:\Users\luke\scoop\apps\git + + +Mode LastWriteTime Length Name +---- ------------- ------ ---- +d----- 24/11/16 8:17 am 2.10.2.windows.1 +d----- 3/1/17 9:42 am 2.11.0.windows.1 +d----l 3/1/17 9:42 am current +``` + +The `2.10.2.windows.1` and `2.11.0.windows.1` directories are the installed versions of Git. + +The `current` directory is not an additional directory, but a **Directory Junction**, pointing to the 2.11.0.windows.1 directory. + +If you're paying close attention, you might notice the extra `l` in the `Mode` column of the output. But apart from that, you won't see much indication that it's any different from a normal directory. + +## What are Directory Junctions? + +If you're not familiar with directory junctions, you can think of them as similar to symbolic links, or even shortcuts. They are pointers to other locations in the file system. There are some important implementation differences between junctions and symbolic links, which you can read about [here]() if you're interested. + +The reason Scoop uses junctions instead of symbolic links is that symbolic links require admin permissions to create (although this [looks set to change soon](https://blogs.windows.com/buildingapps/2016/12/02/symlinks-windows-10/#cpLA6xrKTwb5fOf7.97)). + +### Why Use a Junction? Aren't Shims Enough? + +The main problem being addressed here is how to keep programs working smoothly between updates, even though the new program is in a different directory to the previous one. Shims do solve some of the problems here, by staying in the same place and updating the version that they point to. + +However, some programs need to set environment variables, registry settings or other configuration after installation that point to the actual install path. Before Scoop used `current` directory junctions, these variables and settings would be pointing to the old directory after an upgrade, which was not ideal. By using a `current` alias directory and updating the alias, the settings would continue to point to the right location. + +![Why Junctions?](https://raw.githubusercontent.com/lukesampson/scoop/gh-pages/images/Junctions%20Comparison.png) diff --git a/_wiki/getting-started/Commands.md b/_wiki/getting-started/Commands.md new file mode 100644 index 0000000000..b4853c6ec7 --- /dev/null +++ b/_wiki/getting-started/Commands.md @@ -0,0 +1,44 @@ +# Command Help + +Information on Scoop's commands is built-in. If you use Git you should find the help interface familiar. + +To see a list of commands, run: + +```powershell +scoop help +``` + +To see help on a specific command, run: + +```powershell +scoop help +``` + +The current commands are (output from `scoop help`): + +``` +alias Manage scoop aliases +bucket Manage Scoop buckets +cache Show or clear the download cache +checkup Check for potential problems +cleanup Cleanup apps by removing old versions +config Get or set configuration values +create Create a custom app manifest +depends List dependencies for an app +export Exports (an importable) list of installed apps +help Show help for a command +hold Hold an app to disable updates +home Opens the app homepage +info Display information about an app +install Install apps +list List installed apps +prefix Returns the path to the specified app +reset Reset an app to resolve conflicts +search Search available apps +status Show status and check for new app versions +unhold Unhold an app to enable updates +uninstall Uninstall an app +update Update apps, or Scoop itself +virustotal Look for app's hash on virustotal.com +which Locate a shim/executable (similar to 'which' on Linux) +``` diff --git a/_wiki/getting-started/FAQ.md b/_wiki/getting-started/FAQ.md new file mode 100644 index 0000000000..fdf03d7962 --- /dev/null +++ b/_wiki/getting-started/FAQ.md @@ -0,0 +1,37 @@ +# FAQ + +::: tip +Do you have a question that's not answered here? Please [create an issue](https://github.com/lukesampson/scoop/issues/new). +::: + +## How do I update my apps? + +First, update Scoop to get the latest manifests: + +```powershell +scoop update +``` + +Then update the app, e.g. Git: + +```powershell +scoop update git +``` + +If you want to update all your apps at once, you can use the wildcard `*`: + +```powershell +scoop update * +``` + +## How do I uninstall an app? + +Use `scoop uninstall [app]`. E.g. for Git: + +```powershell +scoop uninstall git +``` + +## Scoop is very slow when installing, locks up the CPU, or shows access denied errors + +It's likely that your antivirus or anti-malware program is doing a realtime scan as files are being extracted. Please see [Antivirus and Anti-Malware Problems](https://github.com/lukesampson/scoop/wiki/Antivirus-and-Anti-Malware-Problems) for more information and possible workarounds. diff --git a/_wiki/getting-started/Quick-Start.md b/_wiki/getting-started/Quick-Start.md new file mode 100644 index 0000000000..9eb4c3a887 --- /dev/null +++ b/_wiki/getting-started/Quick-Start.md @@ -0,0 +1,121 @@ +# Quick Start + +## Requirements + +- Windows 7 SP1+ / Windows Server 2008+ +- [PowerShell 5](https://aka.ms/wmf5download) (or later, including [PowerShell Core](https://docs.microsoft.com/en-us/powershell/scripting/install/installing-powershell-core-on-windows?view=powershell-6)) and [.NET Framework 4.5](https://www.microsoft.com/net/download) (or later) + +::: tip +If you're on Windows 10 or Windows Server 2012 you should be all set, but Windows 7 and Windows Server 2008 might have older versions. You can run `$psversiontable.psversion.major` to get PowerShell version info. +::: + +- PowerShell must be allowed to execute local scripts for your user account + +::: tip +You can configure that by running `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` (`Unrestricted` will work too, but it is less secure, so stick with `RemoteSigned` if you're not sure). +::: + +## Installing Scoop + +Run the following command from your PowerShell to install Scoop to its default location (`C:\Users\\scoop`): + +```powershell +Invoke-Expression (New-Object System.Net.WebClient).DownloadString('https://get.scoop.sh') + +# or shorter +iwr -useb get.scoop.sh | iex +``` + +Once installed, run `scoop help` for instructions. + +The default setup is configured so all user installed programs and Scoop itself live in `C:\Users\\scoop`. +Globally installed programs (`--global`) live in `C:\ProgramData\scoop`. +These settings can be changed through environment variables. + +## Install Scoop to a custom directory by changing `SCOOP` + +Assuming the target directory is `C:\scoop`, in a PowerShell command console, run: + +```powershell +$env:SCOOP='C:\scoop' +[environment]::setEnvironmentVariable('SCOOP',$env:SCOOP,'User') +# run the installer +``` + +Assuming you didn't see any error messages, Scoop is now ready to run. + +## Configure Scoop to install global programs to a custom directory by changing `SCOOP_GLOBAL` + +Assuming the target directory is `C:\apps`, in an admin-enabled PowerShell command console, run: + +```powershell +$env:SCOOP_GLOBAL='c:\apps' +[Environment]::SetEnvironmentVariable('SCOOP_GLOBAL', $env:SCOOP_GLOBAL, 'Machine') +scoop install -g +``` + +## Using Scoop + +Although Scoop is written in PowerShell, its interface is closer to Git and Mercurial than it is to most PowerShell programs. + +To get an overview of Scoop's interface, run: + +```powershell +scoop help +``` + +You'll see a list of commands with a brief summary of what each command does. For more detailed information on a command, run `scoop help `, e.g. `scoop help install` (try it!). + +Now that you have a rough idea of how Scoop commands work, let's try installing something. + +```powershell +scoop install curl +``` + +You'll probably see a warning about a missing hash, but you should see a final message that cURL was installed successfully. Try running it: + +```powershell +curl -L https://get.scoop.sh +``` + +You should see some HTML, probably with a 'document moved' message. Note that, like when you installed Scoop, you didn't need to restart your console for the program to work. Also, if you've installed cURL manually before you might have noticed that you didn't get an error about SSL—Scoop downloaded a certificate bundle for you. + +### Finding apps + +Let's say you want to install the `ssh` command but you're not sure where to find it. Try running: + +```powershell +scoop search ssh +``` + +You'll should see a result for `openssh`. This is an easy case because the name of the app contains 'ssh'. + +You can also find apps by the name of the commands they install. For example, + +```powershell +scoop search hg +``` + +This shows you that the `mercurial` app includes `hg.exe`. + +## Updating Scoop + +To get the latest version of Scoop you have to run the command + +```powershell +scoop update +``` + +This will download the latest version of scoop and updates the local app manifests. + +After you updated Scoop you can update individual apps + +```powershell +scoop update curl +``` + +If you want to update all your installed apps, you can run + +```powershell +scoop update * +``` diff --git a/_wiki/getting-started/Uninstalling-Scoop.md b/_wiki/getting-started/Uninstalling-Scoop.md new file mode 100644 index 0000000000..9437113a87 --- /dev/null +++ b/_wiki/getting-started/Uninstalling-Scoop.md @@ -0,0 +1,19 @@ +# Uninstalling Scoop + +If you've tried Scoop and it's not for you — no problem. You can uninstall Scoop and all the programs you've installed with Scoop by running: + +```powershell +scoop uninstall scoop +``` + +This will let you know what's going to happen and ask if you're sure—just type `y` and press enter to confirm. + +This command will delete the `~/scoop/persist` folder. + +## Broken Install + +If you delete `~/scoop` you should be able to reinstall. To do this, run this in PowerShell: + +```powershell +del .\scoop -Force +``` diff --git a/_wiki/guides/Apache-with-PHP.md b/_wiki/guides/Apache-with-PHP.md new file mode 100644 index 0000000000..32f48d9766 --- /dev/null +++ b/_wiki/guides/Apache-with-PHP.md @@ -0,0 +1,59 @@ +# Apache with PHP + +Install PHP and Apache: + +```powershell +scoop install php apache +``` + +Register the PHP handler with Apache: + +```powershell +iex (new-object net.webclient).downloadstring('https://gist.githubusercontent.com/nilkesede/c98a275b80b6d373131df82eaba96c63/raw/apache-php-init.ps1') +``` + +**To start Apache on the command line**, run: + +```powershell +httpd +``` + +Apache will continue running until you press `Ctrl-C` to terminate it. + +If you open `http://localhost` in your browser, you should see a page saying that “It works!”. + +## The document root directory + +Scoop configures Apache to serve web pages from the `htdocs` directory inside the Scoop install directory. + +You can get to this directory by running: + +```powershell +pushd "\$(scoop which httpd | split-path)\..\htdocs" +``` + +If you would like to serve documents from somewhere else, you need to change the DocumentRoot inside the `conf/httpd.conf` file. You can find `httpd.conf` at + +```powershell +"$(scoop which httpd | split-path)\..\conf\httpd.conf" +``` + +## Installing Apache as a service + +Run: + +```powershell +sudo httpd -k install -n apache +sudo net start apache +``` + +If you don't have `sudo`, you can install it with `scoop install sudo`. + +To uninstall the Apache service + +```powershell +sudo net stop apache +sudo httpd -k uninstall -n apache +``` + +For more information, see [Using Apache HTTP Server on Windows](https://httpd.apache.org/docs/current/platform/windows.html). diff --git a/_wiki/guides/Custom-PHP-configuration.md b/_wiki/guides/Custom-PHP-configuration.md new file mode 100644 index 0000000000..21d74e387d --- /dev/null +++ b/_wiki/guides/Custom-PHP-configuration.md @@ -0,0 +1,52 @@ +# Customize PHP configuration + +If you want to customize the settings of your PHP Installation you should never edit the `php.ini` file inside the PHP directory. This file will not survive updates. + +Always create you own custom configuration files inside the configuration scan dir. +The directory is located at `~/scoop/persist/php/cli/conf.d`. You can create as many `.ini` files as you like. + +## Examples + +Some basic settings like the timezone and limits (`custom.ini`) + +```ini +date.timezone = Europe/Berlin +max_execution_time = 60 +memory_limit = 256M +post_max_size = 128M +upload_max_filesize = 128M +``` + +Enabling debugging (`debug.ini`) + +```ini +display_errors = On +display_startup_errors = On +error_reporting = E_ALL +html_errors = Off +``` + +Enabling PHP modules, those are the most commonly needed modules. Take a look inside the `php.ini` to know what is available (`extensions.ini`) + +```ini +extension_dir=ext + +extension=php_curl.dll +extension=php_fileinfo.dll +extension=php_gd2.dll +extension=php_gettext.dll +extension=php_intl.dll +extension=php_ldap.dll +extension=php_mbstring.dll +extension=php_exif.dll ; Must be after mbstring as it depends on it +extension=php_mysqli.dll +extension=php_openssl.dll +extension=php_pdo_mysql.dll + +extension=php_sqlite3.dll +extension=php_tidy.dll +``` + +::: tip +You can use git to store your configurations. +::: diff --git a/_wiki/guides/Docker.md b/_wiki/guides/Docker.md new file mode 100644 index 0000000000..c12378ff3b --- /dev/null +++ b/_wiki/guides/Docker.md @@ -0,0 +1,62 @@ +# Docker + +## Installing Docker + +```powershell +scoop install docker +``` + +::: tip +Please note that this will not install Docker Engine. +::: + +## Using Docker CLI + +Connect to Docker Engine with [Docker CLI](https://docs.docker.com/engine/reference/commandline/cli/): + +```powershell +docker -H +``` + +The Docker Engine daemon must listen to a [TCP socket](https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-socket-option). + +## Provision Docker Engine with Docker Machine + +Requirements: [Virtualbox](https://www.virtualbox.org/), [VMware](https://www.vmware.com/), Hyper-V or any of the [Docker Machine](https://docs.docker.com/machine/overview/) [drivers](https://docs.docker.com/machine/drivers/) + +1. Create our Docker base machine (will be named _default_): + +```powershell +docker-machine create default +``` + +2. Each time starting working with Docker + +```powershell +docker-machine start +docker-machine env | Invoke-Expression +``` + +3. Then we can bring up any Docker image + +```powershell +docker run ubuntu /bin/echo "Hello world" +``` + +4. When finished: + +```powershell +docker-machine stop +``` + +5. Getting our Docker machine: + +```powershell +docker-machine ls +``` + +### Accessing from WSL environment + +```sh +eval $(docker-machine.exe env docker-host --shell wsl ) && export DOCKER_CERT_PATH=$(wslpath $DOCKER_CERT_PATH) +``` diff --git a/_wiki/guides/Github-with-SSH-key.md b/_wiki/guides/Github-with-SSH-key.md new file mode 100644 index 0000000000..62b4944b41 --- /dev/null +++ b/_wiki/guides/Github-with-SSH-key.md @@ -0,0 +1,64 @@ +# GitHub with SSH Key + +::: tip +Based on [this guide from GitHub](https://help.github.com/articles/generating-ssh-keys#platform-windows). +::: + +Git for Windows comes with a **Git Bash** that gives you good Git functionality over SSH. But what if you want to use PowerShell instead of Bash? This guide shows you how to do just that, **without needing to re-type your password each time you connect**. + +This guide uses Github as an example, but the same principals apply for any SSH-accessible Git repo. + +This assumes you have [installed Scoop](../getting-started/Quick-Start.md), and have a basic knowledge of Git. + +## Install + +First up, install the programs you need: + +```powershell +scoop install git openssh +``` + +## Create a private key + +If you don't already have an SSH key, you can create one like this: + +``` +PS> ssh-keygen +Generating public/private rsa key pair. +Enter file in which to save the key (/c/Users/you//.ssh/id_rsa): [press enter] +Enter passphrase (empty for no passphrase): [type your password] +Enter same passphrase again: [and once more] +... +``` + +Then [add your SSH key to GitHub](https://help.github.com/en/articles/adding-a-new-ssh-key-to-your-github-account). + +## Use `Pshazz` to remember your password + +`Pshazz` includes a plugin for SSH that can save your SSH key password in Windows Credential Manager so you don't need to re-type it every time you push to your Github repo. Install it like this: + +```powershell +scoop install pshazz +``` + +And you can set up git client to store your GitHub access token to Windows Credential Manager by: + +```powershell +git config --global credential.helper manager +``` + +You should see a popup asking for your SSH key password: enter it and check the box to save your password. Back in your PowerShell session, you should see an `Identity Added` message. Whenever you start a PowerShell session from now on, `Pshazz` will make sure the `ssh-agent` is running and load your private key using your saved password. + +## Test it out + +To make sure everything's working, run: + +```powershell +ssh -T git@github.com +``` + +After a warning or two, you should see a message like this: + +``` +Hi ! You've successfully authenticated, but GitHub does not provide shell access. +``` diff --git a/_wiki/guides/Java.md b/_wiki/guides/Java.md new file mode 100644 index 0000000000..99cb493cb0 --- /dev/null +++ b/_wiki/guides/Java.md @@ -0,0 +1,126 @@ +# Java + +## Choice of JDKs + +Java development kits (JDK) and runtime environments (JRE) are available through the [Scoop Java bucket](https://github.com/ScoopInstaller/Java). + +To add the bucket, run: + +```powershell +scoop bucket add java +``` + +### OpenJDK + +[OpenJDK](http://openjdk.java.net) is the preferred JDK (because of its Open Source [license](http://openjdk.java.net/legal/gplv2+ce.html)). + +The Scoop Java bucket contains five different OpenJDK builds. + +#### Oracle OpenJDK + +Oracle's OpenJDK version ([openjdk.json](https://github.com/ScoopInstaller/Java/blob/master/bucket/openjdk.json)) can be installed with: + +```powershell +scoop install openjdk +``` + +#### AdoptOpenJDK + +[AdoptOpenJDK](https://adoptopenjdk.net) has versions with HotSpot and Eclipse OpenJ9 JVMs. + +##### Oracle HotSpot JVM + +- AdoptOpenJDK 12 with Oracle HotSpot JVM + + [adopt12-hotspot.json](https://github.com/ScoopInstaller/Java/blob/master/bucket/adopt12-hotspot.json) can be installed with: + + ```powershell + scoop install adopt12-hotspot + ``` + +- AdoptOpenJDK 12 JRE with Oracle HotSpot JVM (runtime environment) + + [adopt12-hotspot-jre.json](https://github.com/ScoopInstaller/Java/blob/master/bucket/adopt12-hotspot-jre.json) can be installed with: + + ```powershell + scoop install adopt12-hotspot-jre + ``` + +##### Eclipse OpenJ9 JVM + +- AdoptOpenJDK 12 with Eclipse OpenJ9 JVM + + [adopt12-openj9.json](https://github.com/ScoopInstaller/Java/blob/master/bucket/adopt12-hotspot-jre.json) can be installed with: + + ```powershell + scoop install adopt12-openj9 + ``` + +- AdoptOpenJDK 12 JRE with Eclipse OpenJ9 JVM (runtime environment) + + [adopt12-openj9-jre.json](https://github.com/ScoopInstaller/Java/blob/master/bucket/adopt12-hotspot-jre.json) can be installed with: + + ```powershell + scoop install adopt12-openj9-jre + ``` + +#### Zulu + +- [Zulu](https://www.azul.com/products/zulu-and-zulu-enterprise) + +#### ojdkbuild + +- [ojdkbuild](https://github.com/ojdkbuild/ojdkbuild) + +#### Amazon Corretto + +- [Amazon Corretto](https://aws.amazon.com/corretto) + +### Oracle JDK + +[Oracle’s Java](https://www.oracle.com/technetwork/java/index.html) is also available in the [oraclejdk](https://github.com/ScoopInstaller/Java/blob/master/bucket/oraclejdk.json) manifest. + +## Switching Javas + +There are two solutions available today for switching java: + +1. `scoop reset [@]` +2. Using [find-java](https://github.com/lukesampson/scoop-extras/blob/master/bucket/find-java.json) from [extras](https://github.com/lukesampson/scoop-extras) + +`scoop reset` works very well for the current session, and will also update the user's path. + +Globally installed javas takes precedence over user-installed javas, so running `sudo scoop install -g oraclejdk-lts` will install a java that is always default for new sessions. + +### Example of switching between versions + +``` +PS C:> scoop install oraclejdk +Installing 'oraclejdk' (12.0.2-10) [64bit] + +PS C:> scoop install zulu6 +Installing 'zulu6' (6.18.1.5) [64bit] + +PS C:> scoop install openjdk10 +Installing 'openjdk10' (10.0.1) [64bit] + +PS C:> java -version +openjdk version "10.0.1" 2018-04-17 +OpenJDK Runtime Environment (build 10.0.1+10) +OpenJDK 64-Bit Server VM (build 10.0.1+10, mixed mode) + +PS C:> scoop reset zulu6 +Resetting zulu6 (6.18.1.5). +Linking ~\scoop\apps\zulu6\current => ~\scoop\apps\zulu6\6.18.1.5 + +PS C:> java -version +openjdk version "1.6.0-99" +OpenJDK Runtime Environment (Zulu 6.18.1.5-win64) (build 1.6.0-99-b99) +OpenJDK 64-Bit Server VM (Zulu 6.18.1.5-win64) (build 23.77-b99, mixed mode) + +PS C:> scoop reset oraclejdk + +PS C:> java -version +java version "12.0.2" 2019-07-16 +Java(TM) SE Runtime Environment (build 12.0.2+10) +Java HotSpot(TM) 64-Bit Server VM (build 12.0.2+10, mixed mode, sharing) +``` diff --git a/_wiki/guides/SSH-on-Windows.md b/_wiki/guides/SSH-on-Windows.md new file mode 100644 index 0000000000..a6cc3831f9 --- /dev/null +++ b/_wiki/guides/SSH-on-Windows.md @@ -0,0 +1,126 @@ +# SSH + +This guide will help you use SSH on Windows to connect to an SSH server. You'll get a similar experience to how SSH works on Linux on MacOS. No PuTTy or GUIs required, and you can even set it up so you don't have to re-type your private key password every time you connect. + +This guide assumes you have [installed Scoop](../getting-started/Quick-Start.md) and have a Linux machine running an SSH server—we'll need something to connect to. It also assumes that you're basically familiar with [what SSH is all about](http://en.wikipedia.org/wiki/Secure_Shell) and just want to know how to use it on Windows. + +## Install + +::: tip +If you're using Windows 10 version 1803 (April 2018) or above, a built-in `win32-openssh` has been installed in your system and been added to the system PATH. You can run `scoop which ssh` to locate the ssh that you're using, and you can chose to skip external OpenSSH installation. +::: + +First, install SSH from a PowerShell prompt: + +```powershell +scoop install openssh +``` + +P.S. if you want to use ssh with git, you may prefer to install `git-with-openssh` by `scoop install git-with-openssh` + +Or, for the latest version of OpenSSH: + +```powershell +scoop install win32-openssh +``` + +## Connect with SSH using a password + +Say you have a web server running at `example.org`. You should now be able to connect to it with + +```powershell +ssh username@example.org +``` + +Once you enter your password, you should be logged in to the remote server. Pat yourself on the back, you've connected with SSH from Windows! Easy, right? + +Passwords are fine, but for extra security we can use a password-protected key instead. Let's set that up now. + +## Create a key for authentication + +If you already have a private key (e.g. `~/.ssh/id_rsa`) you can skip this step. If not, create a new private key like this (type text is in **bold**): + +``` +PS> ssh-keygen +Generating public/private rsa key pair. +Enter file in which to save the key (/c/Users/username//.ssh/id_rsa): [enter] +Enter passphrase (empty for no passphrase): your-super-secret-password +Enter same passphrase again: your-super-secret-password +Your identification has been saved in /c/Users/username//.ssh/id_rsa. +Your public key has been saved in /c/Users/username//.ssh/id_rsa.pub. +The key fingerprint is: +d5:96:01:96:7a:63:25:93:a0:d6:65:0b:1a:a3:e7:05 username@COMPUTER +The key's randomart image is: ++--[ RSA 2048]----+ +| E o.=+. | +| . B ==o.o | +| . = o.o++ | +| + ...+. | +| . So . | +| | +| | +| | +| | ++-----------------+ +``` + +If you used the default file as above, your private key will be created at `~/.ssh/id_rsa` and your public key will be at `~/.ssh/id_rsa.pub`. + +## Connect with an SSH key + +Before we can connect to our server (e.g. `example.org`) with our SSH key, we need to authorize the key we'll be using by copying our public key to the remote server: + +```powershell +cat ~/.ssh/id_rsa.pub | ssh username@example.org 'mkdir -p ~/.ssh; cat >> ~/.ssh/authorized_keys' +``` + +Now try connecting again: + +```powershell +ssh username@example.org +``` + +This time, instead of being asked for your `username` password, you should be asked for the password for your private key. + +## Better SSH experience with `Pshazz` + +Now, every time you restart your PC and open a console session you need to start the SSH Agent manually, and every time you connect with `ssh username@example.org` you'll be asked for the private key password. + +You can use [`Pshazz`](https://github.com/lukesampson/pshazz) to automatically start the SSH Agent and cache your the key passphrase. + +```powershell +scoop install pshazz +``` + +Then `Pshazz` will start the SSH Agent automatically and add your keys. You'll be asked for the key passphrase for the first time. Try connecting over SSH: + +```powershell +ssh username@example.org +``` + +If everything went according to plan, you should be logged in without needing to enter your password. Hooray! + +To see what happened, type: + +```powershell +ssh-add -l +``` + +The thumbprint for your SSH key should be shown. `ssh-agent` will try using this key whenever you use SSH now. + +What's more, `Pshazz` support tab completion on `ssh` command: + +```powershell +ssh +``` + +You will see all hosts in your `~/.ssh/config`. + +You might notice that your SSH sessions are timing out. To prevent this I like to add a ServerAliveInterval to my `~/.ssh/config` (you might need to create this file if it doesn't exist): + +``` +Host * + ServerAliveInterval 30 +``` + +This will send a null packet to the remote server every 30 seconds to keep the connection alive. diff --git a/_wiki/guides/Theming-Powershell.md b/_wiki/guides/Theming-Powershell.md new file mode 100644 index 0000000000..735112f331 --- /dev/null +++ b/_wiki/guides/Theming-Powershell.md @@ -0,0 +1,38 @@ +# Theming Powershell + +![](https://github.com/lukesampson/scoop/raw/gh-pages/images/docs/shell-theme.png) + +This is how my command line looks, running Powershell in the built-in Windows Console. You can see the [Solarized](http://ethanschoonover.com/solarized) color theme, and a custom prompt including Git info. You can't see Git tab completions or support for SSH keys, but those are there too. + +I used [Concfg](https://github.com/lukesampson/concfg) for the font and color theme, and [Pshazz](https://github.com/lukesampson/pshazz) for the custom prompt and Git and SSH features. + +Here's my script to get this setup: + +```powershell +scoop install 7zip git openssh concfg + +# back-up current console settings +concfg export console-backup.json + +# use solarized color theme +concfg import solarized-dark + +# You'll see this warning: +# overrides in the registry and shortcut files might interfere with +# your concfg settings. +# would you like to search for and remove them? (Y/n): +# Enter 'n' if you're not sure yet: you can always run 'concfg clean' later + +scoop install pshazz +``` + +If you install Pshazz and you already have an SSH key, you'll see a popup asking for your password. +![](https://github.com/lukesampson/scoop/raw/gh-pages/images/docs/askpass.png) + +There's [more info on setting up SSH with Scoop](SSH-on-Windows.md), if you're interested. + +Now you should have a nicer looking command prompt, with some helpful Git and SSH enhancements. If you want to customize your prompt even more, check out the [Concfg](https://github.com/lukesampson/concfg) and [Pshazz](https://github.com/lukesampson/pshazz) projects on GitHub. + +It's worth pointing out that concfg works in ye olde cmd.exe as well, but with Powershell you get the extra prompt enhancements, plus a great dynamic and functional programming language at your fingertips as well. + +If you don't like your new color theme and want to go back, run `concfg import console-backup.json`. If you start a new console and find your color settings are gone, re-run `concfg import solarized small` and enter 'y' when it asks if you'd like to clean registry settings. diff --git a/_wiki/misc/Antivirus-and-Anti-Malware-Problems.md b/_wiki/misc/Antivirus-and-Anti-Malware-Problems.md new file mode 100644 index 0000000000..d7159ac5fa --- /dev/null +++ b/_wiki/misc/Antivirus-and-Anti-Malware-Problems.md @@ -0,0 +1,20 @@ +# Antivirus and Anti Malware Problems + +If you are experiencing performance problems during Scoop installs—like high CPU usage, or file access denied errors—it's possible that an anti-malware or anti-virus program is scanning files as they are being extracted and installed. + +## Windows Defender + +You can exclude the directories that Scoop uses from realtime scanning by running this command as an administrator: + +```powershell +Add-MpPreference -ExclusionPath "$($env:programdata)\scoop", "$($env:scoop)" +``` + +If you want to undo this change and re-enable realtime scanning of these directories: + +```powershell +Remove-MpPreference -ExclusionPath "$($env:programdata)\scoop", "$($env:scoop)" +``` + +References: +[Issue #1388](https://github.com/lukesampson/scoop/issues/1388) diff --git a/_wiki/misc/Can-I-Use-Scoop-in-Bash.md b/_wiki/misc/Can-I-Use-Scoop-in-Bash.md new file mode 100644 index 0000000000..cd7f51ff55 --- /dev/null +++ b/_wiki/misc/Can-I-Use-Scoop-in-Bash.md @@ -0,0 +1,19 @@ +# Can I use Scoop in Bash? + +## Short Answer: Yes! + +Add this line to your `~/.bashrc` (or `~/.bash_profile` if you're using `git bash`, or `~/.profile` if you're using `busybox`) + +```sh +function scoop() { powershell -ex unrestricted scoop.ps1 "$@" ;} && export -f scoop +``` + +Restart bash or run `source ~/.bashrc` and Scoop will now work. + +::: tip NOTE +functions are [preferred](https://askubuntu.com/a/98791) over aliases because aliases are only set in the current shell, whereas functions (once exported) [can be called from within scripts](https://unix.stackexchange.com/a/22867). +::: + +## Long Answer + +When you're in bash: if you use Scoop, PowerShell needs to be started up every time you call the alias. You'll notice that it can take a while. So the question is, should you use Scoop in bash? diff --git a/_wiki/misc/Criteria-for-including-apps-in-the-main-bucket.md b/_wiki/misc/Criteria-for-including-apps-in-the-main-bucket.md new file mode 100644 index 0000000000..e756b82049 --- /dev/null +++ b/_wiki/misc/Criteria-for-including-apps-in-the-main-bucket.md @@ -0,0 +1,9 @@ +# Criteria for including apps in the main bucket + +For an app to be acceptable for the [main bucket](https://github.com/ScoopInstaller/Main), it should be: + +- A reasonably well-known and widely used developer tool +- The latest stable version of the program +- The full version i.e. not a trial version +- A fairly standard install (e.g. uses a version-specific download URL, no elaborate pre/post install scripts) +- A non-GUI tool diff --git a/_wiki/misc/Example-Setup-Scripts.md b/_wiki/misc/Example-Setup-Scripts.md new file mode 100644 index 0000000000..3e6ed0bb2f --- /dev/null +++ b/_wiki/misc/Example-Setup-Scripts.md @@ -0,0 +1,53 @@ +# Example Setup Scripts + +Here are some example "get-all-my-stuff" scripts. + +It's assumed that you have PowerShell 5 and you've already installed Scoop, e.g. + +```powershell +iex (new-object net.webclient).downloadstring('https://get.scoop.sh') +set-executionpolicy unrestricted -s cu +``` + +## Example dev environment setup + +```powershell +# utils +scoop install 7zip curl sudo git openssh coreutils grep sed less + +# programming languages +scoop install python ruby go nodejs + +# WAMP stack +scoop install apache mariadb php +iex (new-object net.webclient).downloadstring('https://gist.github.com/lukesampson/6546858/raw/apache-php-init.ps1') + +# console theme +scoop install concfg pshazz +concfg import solarized small + +# vim +scoop install vim +' +set ff=unix + +set cindent +set tabstop=4 +set shiftwidth=4 +set expandtab +set backupdir=$TEMP +' | out-file ~/.vimrc -enc oem -append + +``` + +## Example production environment setup + +```powershell +scoop install sudo 7zip + +# make these available to system processes +sudo scoop install git ruby postgres --global + +# just for me +scoop install grep coreutils +``` diff --git a/_wiki/misc/Global-Installs.md b/_wiki/misc/Global-Installs.md new file mode 100644 index 0000000000..bd459943df --- /dev/null +++ b/_wiki/misc/Global-Installs.md @@ -0,0 +1,33 @@ +# System-wide (global) installs + +By default, Scoop installs apps just for your user account. Apps are installed under `~\scoop\apps`, and only your environment variables are modified. This is usually fine, especially in your dev environment. + +In some cases you might want to install an app system-wide so that it's accessible to other users, including the local system account. Scoop provides a `--global` switch to support this case. + +Global installs require admin permissions, because they install to `%SYSTEMDRIVE%\ProgramData\scoop`, and set system environment variables. For this reason, this example uses the `sudo` command, which is a rough equivalent of the UNIX command to run a command with superuser privileges. You can install this by running: + +```powershell +scoop install sudo +``` + +Otherwise, you can just open a normal PowerShell console using Run As Administrator. + +## Examples + +To install an app: + +```powershell +sudo scoop install git --global +``` + +::: tip +If you want the app to be available to the local system account, you will need to restart the system after you install your first app globally. This is because changes made to environment variables don't take affect for the local system account until you restart Windows (see [here](https://support.microsoft.com/kb/821761)). +::: + +You can also use the short form for `--global`, `-g`. + +E.g. to update a globally installed app using the short form: + +```powershell +sudo scoop update git -g +``` diff --git a/_wiki/misc/Multi-connection-downloads-with-aria2.md b/_wiki/misc/Multi-connection-downloads-with-aria2.md new file mode 100644 index 0000000000..002bd17112 --- /dev/null +++ b/_wiki/misc/Multi-connection-downloads-with-aria2.md @@ -0,0 +1,15 @@ +# Multi-connection downloads with `aria2` + +Scoop can utilize [`aria2`](https://github.com/aria2/aria2) to use multi-connection downloads. Simply install `aria2` through Scoop and it will be used for all downloads afterward. + +```powershell +scoop install aria2 +``` + +You can tweak the following `aria2` settings with the `scoop config` command: + +- aria2-enabled (default: true) +- [aria2-retry-wait](https://aria2.github.io/manual/en/html/aria2c.html#cmdoption-retry-wait) (default: 2) +- [aria2-split](https://aria2.github.io/manual/en/html/aria2c.html#cmdoption-s) (default: 5) +- [aria2-max-connection-per-server](https://aria2.github.io/manual/en/html/aria2c.html#cmdoption-x) (default: 5) +- [aria2-min-split-size](https://aria2.github.io/manual/en/html/aria2c.html#cmdoption-k) (default: 5M) diff --git a/_wiki/misc/PowerShell-Modules.md b/_wiki/misc/PowerShell-Modules.md new file mode 100644 index 0000000000..3531d7df29 --- /dev/null +++ b/_wiki/misc/PowerShell-Modules.md @@ -0,0 +1,23 @@ +# PowerShell modules + +PowerShell modules are installed like other apps, but they are also linked under `~\scoop\modules`. + +The `~\scoop\modules` directory will be added to your `$env:PSModulePath` environment variable, and PowerShell should automatically detect the modules you install here using Scoop. + +The directories under `~\scoop\modules` aren't normal directories. Each is a **directory junction** which points to the currently installed version of the app/module, which is itself a directory junction pointing to the actual versioned directory. So for a module named `MyPSModule` you might have something like this: + +`~\scoop\modules\MyPSModule`
+  → _points to_ `~\scoop\apps\mypsmodule\current`
+    → _points to_ `~\scoop\apps\mypsmodule\1.16.0.rc2` + +The key part of the [Scoop manifest](../concepts/App-Manifests.md) for a PowerShell module is this: + +```json +{ + "psmodule": { + "name": "NameOfTheModule" + } +} +``` + +The `name` property is required if you use `psmodule`, and it should match the name of the `.psd1` manifest for the PowerShell module for PowerShell to consider it "well-formed" and automatically detect the module (see [here]() for more.) diff --git a/_wiki/misc/Switching-Ruby-and-Python-Versions.md b/_wiki/misc/Switching-Ruby-and-Python-Versions.md new file mode 100644 index 0000000000..d72c4ca650 --- /dev/null +++ b/_wiki/misc/Switching-Ruby-and-Python-Versions.md @@ -0,0 +1,45 @@ +# Switching between Ruby and Python Versions + +## `scoop reset` + +If you need to run multiple versions of Ruby or Python on the same computer, you can use `scoop reset` to switch between versions. +If you're familiar with `rbenv` or RVM this is roughly similar, although with `scoop reset` you always need to switch version manually. + +## Ruby + +```powershell +scoop bucket add versions # add the 'versions' bucket if you haven't already + +scoop install ruby ruby19 +ruby --version # -> ruby 1.9.3p551 (2014-11-13) [i386-mingw32] + +# switch to ruby 2.x +scoop reset ruby +ruby --version # -> ruby 2.3.3p222 (2016-11-21 revision 56859) [x64-mingw32] + +# switch back to 1.9.x +scoop reset ruby19 +ruby --version # -> ruby 1.9.3p551 (2014-11-13) [i386-mingw32] +``` + +`scoop reset` re-installs shims for the app and updates environment variables according to the app manifest. +You can switch between Ruby versions as many times as you like—both versions remain installed but one takes priority. + +## Python + +The same thing works for Python + +```powershell +scoop bucket add versions # add the 'versions' bucket if you haven't already + +scoop install python27 python +python --version # -> Python 3.6.2 + +# switch to python 2.7.x +scoop reset python27 +python --version # -> Python 2.7.13 + +# switch back (to 3.x) +scoop reset python +python --version # -> Python 3.6.2 +``` diff --git a/_wiki/misc/Using-Scoop-behind-a-proxy.md b/_wiki/misc/Using-Scoop-behind-a-proxy.md new file mode 100644 index 0000000000..4797046404 --- /dev/null +++ b/_wiki/misc/Using-Scoop-behind-a-proxy.md @@ -0,0 +1,84 @@ +# Using Scoop behind a proxy server + +## Do you need this? + +If your proxy is already configured in Internet Options and it doesn't require authentication, you shouldn't need to do anything else for Scoop to use it. + +These instructions are for people who + +1. need to authenticate with their proxy, either using their Windows credentials or another username/password +2. want to use a proxy server for Scoop that isn't configured in Internet Options. + +## Installation + +Normally, Scoop is installed with: + +```powershell +iex (new-object net.webclient).downloadstring('https://get.scoop.sh') +``` + +If you're behind a proxy you might need to run one or more of these commands first: + +```powershell +# If you want to use a proxy that isn't already configured in Internet Options +[net.webrequest]::defaultwebproxy = new-object net.webproxy "http://proxy.example.org:8080" + +# If you want to use the Windows credentials of the logged-in user to authenticate with your proxy +[net.webrequest]::defaultwebproxy.credentials = [net.credentialcache]::defaultcredentials + +# If you want to use other credentials (replace 'username' and 'password') +[net.webrequest]::defaultwebproxy.credentials = new-object net.networkcredential 'username', 'password' +``` + +These commands will affect any web requests using `net.webclient` until the end of your PowerShell session. + +## Configuring Scoop to use your proxy + +Once Scoop is installed, you can use `scoop config` to configure your proxy. Here's an excerpt from `scoop help config`: + +> `scoop config proxy [username:password@]host:port` + +By default, Scoop will use the proxy settings from Internet Options, but with anonymous authentication. + +- To use the credentials for the current logged-in user, use `currentuser` in place of `username:password` +- To use the system proxy settings configured in Internet Options, use `default` in place of `host:port` +- An empty or unset value for proxy is equivalent to `default` (with no username or password) +- To bypass the system proxy and connect directly, use `none` (with no username or password) + +## Config examples + +### Use your Windows credentials with the default proxy configured in Internet Options + +```powershell +scoop config proxy currentuser@default +``` + +### Use hard-coded credentials with the default proxy configured in Internet Options + +```powershell +scoop config proxy user:password@default +``` + +### Use a proxy that isn't configured in Internet Options + +```powershell +# anonymous authentication to proxy.example.org on port 8080: +scoop config proxy proxy.example.org:8080 + +# or, with authentication: +scoop config proxy username:password@proxy.example.org:8080 +``` + +### Bypassing the proxy configured in Internet Options + +```powershell +scoop config rm proxy +``` + +### Using a password containing `@` or `:` + +If your proxy password contains `@` or `:` characters, you need to escape them using a `\`, e.g.: + +```powershell +scoop config proxy 'username:p\@ssword@proxy.example.org:8080' +``` diff --git a/_wiki/misc/Why-PowerShell.md b/_wiki/misc/Why-PowerShell.md new file mode 100644 index 0000000000..88138d116e --- /dev/null +++ b/_wiki/misc/Why-PowerShell.md @@ -0,0 +1,30 @@ +# Why PowerShell? + +Scoop tries to "just work" whether you run it from PowerShell or CMD, but **I recommend using PowerShell** instead. Here's why. + +## Yes, PowerShell has problems + +- The `Verb-Noun` verbosity, commands that were seemingly not designed to be typed +- The ISE—a GUI for a command line interface. I know the commands are hard to type—but is point-and-clicking a solution? +- The name PowerShell, and the unofficial abbreviation PoSH. Cringe. +- “Everything's an object!” ends up feeling clumsy. Sometimes text is just easier to work with. Support for primitives, arrays and hashes would have been enough. +- Modules. Who knows how they work? +- Doesn't seem like a first class shell within Windows +- The built-in parameter parsing isn't good +- A heavy "sysadmin" feel that makes developers/DevOps sad + +## Nevertheless... + +You should still use PowerShell. Why? Because you can ignore most of these problems, and you're still left with a great, flexible, dynamic, functional scripting language. + +You don't have to write `Verb-Noun` "cmdlets", just write a script. Return text from your PowerShell scripts if you want —— because text is the universal interface. Parse your own parameters (or dot-source [getopt](https://github.com/lukesampson/psutils/blob/master/getopt.ps1)). If someone mentions PoSH, ridicule them publicly (kidding). + +So once you ignore the bad points, what are you left with? + +- **A very capable programming environment**, much more so than cmd.exe. +- **A fast REPL** (like ScriptCS, but easier and more dynamic) +- **The only scripting language that you can rely on being installed on Windows** +- **Great language support for primitive types, arrays and hashes** +- **The feeling of pride that comes from using an obscure shell**. Zsh? Fish? Pfft. Virtually _no-one_ uses PowerShell (not sure on the actual numbers there). + +Yes, you're stuck using the ancient and seemingly-forgotten Windows Console, but you can get that working fairly nicely with [a little customization](../guides/Theming-Powershell.md). diff --git a/_wiki/overview/Chocolatey-Comparison.md b/_wiki/overview/Chocolatey-Comparison.md new file mode 100644 index 0000000000..cb593ddb62 --- /dev/null +++ b/_wiki/overview/Chocolatey-Comparison.md @@ -0,0 +1,13 @@ +# How is Scoop different from [Chocolatey](http://chocolatey.org)? + +- **Installs to ~/scoop/ by default.** You can set up your own programs and not worry that they'll interfere with other users' programs (or theirs with yours, perhaps more importantly). You can optionally choose to install programs system-wide if you have administrator rights. +- **No UAC popups, doesn't require admin rights.** Since programs are installed just for your user account, you won't be interrupted by UAC popups. +- **Doesn't pollute your path.** Where possible, Scoop puts your program shims in a single directory and just adds that to your path. +- **Doesn't use NuGet.** NuGet is a great solution to the problem of managing software library dependencies. Scoop avoids this problem altogether: each program you install is isolated and independent. +- **Simpler than packaging.** Scoop isn't a package manager, rather it reads plain JSON manifests that describe how to install a program and its dependencies. +- **Simpler app repository.** Scoop just uses Git for its app repository. You can create your own repo, or even just a single file that describes an app to install. +- **Can't always install a specific version of a program.** For some programs, scoop can install an older version of a program, via `scoop install app@version`. For example, `scoop install curl@7.56.1`. This functionality only works if the old version is still available online. Some older versions have specific installers, such as Python 2.7 and Ruby 1.9, which are commonly required. These can be installed from the [versions](https://github.com/scoopinstaller/versions) bucket via `scoop install python27` and `scoop install ruby19`. + +::: tip NOTE +While it would be easy to install Skype with Scoop, this will probably never be in Scoop's main bucket (app repository). Scoop focuses on open-source, command-line developer tools. The [scoop extras](https://github.com/lukesampson/scoop-extras) bucket is for non developer tools. +::: diff --git a/_wiki/overview/Cygwin-and-MSYS-Comparison.md b/_wiki/overview/Cygwin-and-MSYS-Comparison.md new file mode 100644 index 0000000000..d26520b48f --- /dev/null +++ b/_wiki/overview/Cygwin-and-MSYS-Comparison.md @@ -0,0 +1,20 @@ +# How is Scoop different from Cygwin and MSYS? + +The most concise description of these 2 projects is an answer by Mike Zick in [this thread](http://sourceforge.net/mailarchive/forum.php?thread_name=200506130821.11185.mszick%40morethan.org&forum_name=mingw-msys). + +> Cygwin is an operating system wrapper +> The goal of Cygwin is to provide a Linux Programming API. +> +> Msys is a command shell substitute +> The goal of Msys is to provide a POSIX scripting environment. + +It's probably not a completely accurate or comprehensive description, but it is fairly easy to grasp. + +So to parallel this for Scoop: + +**Scoop is an installer** +**The goal of Scoop is to let you use Unix-y programs in a normal Windows environment** + +Using Scoop lets you achieve similar things to Cygwin and MSYS, but without having to learn about and use a separate environment. You can just keep doing what you're already doing but easily access the cross-platform tools you need. + +As it happens, a lot of the programs that Scoop installs either come directly from the MinGW/MSYS project, or were built using their tools. Scoop can only hope to achieve its goals because of 15 years of amazing work on MinGW/MSYS, which itself is based on Cygwin. diff --git a/_wiki/overview/So-What.md b/_wiki/overview/So-What.md new file mode 100644 index 0000000000..86535144e6 --- /dev/null +++ b/_wiki/overview/So-What.md @@ -0,0 +1,41 @@ +# So What? + +## Why should you care about Scoop? + +If you identify with lots of the following statements, then Scoop has been designed with you in mind. + +- You're a programmer/developer +- You want to set up a machine without having to visit a bunch of websites, download installers and then click through each one +- You're comfortable working on the command line, especially with tools like Git +- You're familiar with UNIX tools, and you wish there were more of them on Windows +- You read Hacker News and you feel like you're 'stuck' on Windows and missing out on lots of cool things +- You wish there was an easier way to tell other developers how to install programs (maybe your own programs) +- You use Homebrew/apt-get and think, "this is awesome". + +## What does Scoop feature? + +- Lets you script your development/production environment setup (repeatable!) +- Installs tools so they 'just work', the way they work on other platforms (e.g. SSH) +- Lets you stay on the command line, where you can work fast +- Extends PowerShell so you can use programs that work really well with text, the universal interface. +- Lets you sharpen skills that transfer to Linux and macOS + +## But I already use X, why should I use Scoop? + +There are similar tools available, like [Chocolatey](http://chocolatey.org), [Ninite](http://ninite.com) and [CoApp](http://coapp.org). While there's a more in-depth comparison with Chocolatey [here](Chocolatey-Comparison.md), here are some general reasons why you might like to try Scoop. + +Scoop: + +- avoids GUIs whenever possible, keeps you on the command line +- installs to your home directory by default (thereby avoiding UAC popups, and other people messing up your setup) +- installs applications independently and in a self-contained way (which means less conflicts, easy to undo installs) +- doesn't pollute your path +- has a command interface similar to Git and similar tools +- makes it easy to discover commands that you don't know, or have forgotten +- makes it easy to tell people how to install your programs +- has a curated collection of apps, while at the same time... +- makes it easy to create your own apps and collections of apps +- values your time and attention +- reads the README for you + +There are other, less objective reasons to give Scoop a try. Maybe you want to be able to install apps without Admin privileges. Maybe you like Chocolatey but you don't like the name, or typing `cinst` feels weird, or you're not a fan of messages about "Chocolatey gods".