Skip to content

Commit 1ae871a

Browse files
waruqiwaruqi
committed
update docs
1 parent 106c665 commit 1ae871a

File tree

2 files changed

+308
-198
lines changed

2 files changed

+308
-198
lines changed

‎mirror/package/local_package.html

Lines changed: 202 additions & 92 deletions
Original file line numberDiff line numberDiff line change
@@ -92,7 +92,7 @@ <h4>This is a mirror page, please see the original page: </h4><a href="https://x
9292
line-height: 1;
9393
}
9494
</style>
95-
<h3 id="defaultpackagingformat">Default packaging format</h3>
95+
<h3 id="generatelocalpackage">Generate local package</h3>
9696
<p>After version 2.5.5, we have provided a new local package packaging solution that will seamlessly integrate <code>add_requires</code> and <code>add_packages</code>.</p>
9797
<p>We can execute the <code>xmake package</code> command to generate the default new version of the packaging format.</p>
9898
<pre><code class="lang-console">$ xmake package
@@ -150,6 +150,97 @@ <h3 id="defaultpackagingformat">Default packaging format</h3>
150150
-L/Users/ruki/projects/personal/xmake/tests/actions/package/localpkg/bar/build/packages/a/add/macosx/x86_64/release/lib
151151
-Wl,-x -lfoo -lsub -ladd -lz
152152
</code></pre>
153+
<h4 id="stepbysteplocalpackagingtutorial">Step by Step Local Packaging Tutorial</h4>
154+
<p>In this tutorial we will package a static library called foo, upload it to a GitHub repository and consume it similar to a manner of CMake FetchContent</p>
155+
<ul>
156+
<li>Create an xmake project</li>
157+
</ul>
158+
<pre><code class="lang-bash">$ xmake create -P package_origin
159+
</code></pre>
160+
<ul>
161+
<li>Imitate this filetree to prepare files for your package</li>
162+
</ul>
163+
<pre><code class="lang-bash">│ .gitignore
164+
│ xmake.lua
165+
└───src
166+
│ main.cpp
167+
├───inc
168+
│ └───foo
169+
│ foo.hpp
170+
└───lib
171+
└───foo
172+
foo.cpp
173+
</code></pre>
174+
<ul>
175+
<li>Create static library target in xmake</li>
176+
</ul>
177+
<pre><code class="lang-lua">target("foo")
178+
set_kind("static")
179+
add_files("src/lib/foo/*.cpp")
180+
add_headerfiles("src/inc/foo/*.hpp")
181+
add_includedirs("src/inc/foo", {public = true})
182+
</code></pre>
183+
<ul>
184+
<li>Implement the functionality of your target</li>
185+
</ul>
186+
<p>foo.hpp</p>
187+
<pre><code class="lang-cpp">void foo();
188+
</code></pre>
189+
<p>foo.cpp</p>
190+
<pre><code class="lang-cpp">#include <iostream>
191+
#include "foo.hpp"
192+
193+
void foo() {
194+
std::cout << "foo";
195+
}
196+
</code></pre>
197+
<ul>
198+
<li>Build your project and create the package</li>
199+
</ul>
200+
<pre><code class="lang-bash">$ xmake build
201+
$ xmake package foo
202+
</code></pre>
203+
<ul>
204+
<li>Move packages artifacts to a custom package repository.</li>
205+
</ul>
206+
<pre><code class="lang-bash">$ mkdir my_custom_binary_package_repo
207+
$ cp -r build/packages my_custom_binary_package_repo/packages
208+
$ cd my_custom_binary_package_repo
209+
$ git init
210+
$ git add .
211+
$ git commit -a -m "init"
212+
</code></pre>
213+
<p>Then push this new package repository to your custom repository, e.g. <code>https://github.com/xxx/my_custom_binary_package_repo.git</code></p>
214+
<ul>
215+
<li>Create a project where you intend on consuming the package</li>
216+
</ul>
217+
<pre><code class="lang-bash">$ xmake create package_consumption
218+
</code></pre>
219+
<ul>
220+
<li>Consume the package by adding the repository, finding the package and then linking the package to target of your choosing</li>
221+
</ul>
222+
<pre><code class="lang-lua">add_repositories("foo https://github.com/xxx/my_custom_binary_package_repo.git")
223+
add_requires("foo")
224+
225+
target("package_consumption")
226+
set_kind("binary")
227+
add_files("src/*.cpp")
228+
add_packages("foo")
229+
</code></pre>
230+
<p>you can also use local repository.</p>
231+
<pre><code class="lang-lua">add_repositories("foo /localpath/my_custom_binary_package_repo")
232+
</code></pre>
233+
<pre><code class="lang-cpp">#include "foo.hpp"
234+
int main() {
235+
foo();
236+
return 0;
237+
}
238+
</code></pre>
239+
<p>Congratulations, you have packaged a library and consumed it xmake!</p>
240+
<pre><code class="lang-bash">$ xmake build
241+
$ xmake run
242+
foo
243+
</code></pre>
153244
<h3 id="generateremotepackage">Generate remote package</h3>
154245
<p>Out of the local package format, <code>xmake package</code> now also supports generating remote packages, so that users can quickly submit them to remote warehouses.</p>
155246
<p>We only need to modify the package format when packaging.</p>
@@ -182,6 +273,116 @@ <h3 id="generateremotepackage">Generate remote package</h3>
182273
<pre><code class="lang-console">$ xmake package -f remote --url=https://xxxx/xxx.tar.gz --shasum=xxxxx --homepage=xxxxx`
183274
</code></pre>
184275
<p>xmake will also read the relevant configuration information from the target&#39;s <code>set_license</code> and <code>set_version</code> configurations.</p>
276+
<h4 id="stepbystepremotepackagingtutorial">Step by Step Remote Packaging Tutorial</h4>
277+
<h5 id="introduction">Introduction</h5>
278+
<p>A remote package is a package that is compiled from source. If you&#39;re developing cross-platform libraries, remote packages allow you to avoid manually compiling for every library and platform.</p>
279+
<p>To create remote packages:</p>
280+
<ol>
281+
<li>Upload your source code to a repository.</li>
282+
<li>In a <strong>separate repository</strong>, create a remote package manifest that points to your source repository.</li>
283+
</ol>
284+
<p>To consume remote packages, you need to add the repository that contains the remote package manifest to your project, find the package, and then add it to your desired target. </p>
285+
<h5 id="example">Example</h5>
286+
<p>In this example, we’ll create a remote package for a static library named <code>foo</code>, built using <strong>Windows with MSVC</strong>, and then <strong>consume it on MSYS2 using Clang</strong>.</p>
287+
<ul>
288+
<li>Create an xmake project</li>
289+
</ul>
290+
<pre><code class="lang-bash">xmake create package_remote_origin
291+
</code></pre>
292+
<ul>
293+
<li>Imitate this filetree to prepare files for your package</li>
294+
</ul>
295+
<pre><code class="lang-bash">│
296+
├── .gitignore
297+
├── xmake.lua
298+
└── src
299+
├── main.cpp
300+
├── inc
301+
│ └── foo
302+
│ └── foo.hpp
303+
└── lib
304+
└── foo
305+
└── foo.cpp
306+
</code></pre>
307+
<ul>
308+
<li>Create static library target in xmake</li>
309+
</ul>
310+
<pre><code class="lang-lua">target("foo")
311+
set_kind("static")
312+
add_files("src/lib/foo/*.cpp")
313+
add_headerfiles("src/inc/foo/*.hpp")
314+
add_includedirs("src/inc/foo", {public = true})
315+
</code></pre>
316+
<ul>
317+
<li>Implement the functionality of your target</li>
318+
</ul>
319+
<p>foo.hpp</p>
320+
<pre><code class="lang-cpp">void foo();
321+
</code></pre>
322+
<p>foo.cpp</p>
323+
<pre><code class="lang-cpp">#include <iostream>
324+
#include "foo.hpp"
325+
326+
void foo() {
327+
std::cout << "foo";
328+
}
329+
</code></pre>
330+
<ul>
331+
<li>Create a package and point to your source repository in the config file</li>
332+
</ul>
333+
<pre><code class="lang-bash">xmake package -f remote foo
334+
</code></pre>
335+
<ul>
336+
<li>Create a source repository for your package with a version tag</li>
337+
</ul>
338+
<p>For example, you can pust to <code>https://github.com/xxx/foo_remote_package_source.git</code> with tag v1.0.0</p>
339+
<p>Then edit package configuration to add the given version.</p>
340+
<pre><code class="lang-lua">package("foo")
341+
add_urls("https://github.com/xxx/foo_remote_package_source.git")
342+
add_versions("1.0.0", "v1.0.0")
343+
</code></pre>
344+
<p>Or you can use .tar.gz as git url and add it&#39;s sha256 sum to versions.</p>
345+
<ul>
346+
<li>Create a package config repository for your package</li>
347+
</ul>
348+
<pre><code class="lang-bash">$ mkdir mycustom_remote_package_repo
349+
$ mv build/packages mycustom_remote_package_repo
350+
$ cd mycustom_remote_package_repo
351+
$ git init
352+
$ git add .
353+
$ git commit -a -m "init repository"
354+
</code></pre>
355+
<p>You can push this repository to <a href="https://github.com/xxx/mycustom_remote_package_repo.git">https://github.com/xxx/mycustom_remote_package_repo.git</a></p>
356+
<ul>
357+
<li>Create a project where you intend on consuming the package</li>
358+
</ul>
359+
<pre><code class="lang-bash">$ xmake create package_consumption
360+
</code></pre>
361+
<ul>
362+
<li>Consume the package by adding the repository, finding the package and then linking the package to target of your choosing</li>
363+
</ul>
364+
<pre><code class="lang-lua">add_repositories("foo https://github.com/xxx/mycustom_remote_package_repo.git")
365+
add_requires("foo")
366+
367+
target("package_consumption")
368+
set_kind("binary")
369+
add_files("src/*.cpp")
370+
add_packages("foo")
371+
</code></pre>
372+
<p>you can also use local repository.</p>
373+
<pre><code class="lang-lua">add_repositories("foo /localpath/mycustom_remote_package_repo")
374+
</code></pre>
375+
<pre><code class="lang-cpp">#include "foo.hpp"
376+
int main() {
377+
foo();
378+
return 0;
379+
}
380+
</code></pre>
381+
<p>Congratulations, you have packaged a library and consumed it xmake!</p>
382+
<pre><code class="lang-bash">$ xmake build
383+
$ xmake run
384+
foo
385+
</code></pre>
185386
<h3 id="findpackagesfromcmake">Find packages from CMake</h3>
186387
<p>Now cmake is the de facto standard, so the find_package provided by CMake can already find a large number of libraries and modules. We fully reuse this part of cmake&#39;s ecology to expand xmake&#39;s integration of packages.</p>
187388
<p>We can use <code>find_package("cmake::xxx")</code> to find some packages with cmake, xmake will automatically generate a cmake script to call cmake&#39;s find_package to find some packages and get the bread information.</p>
@@ -260,97 +461,6 @@ <h4 id="specifythesearchmode">Specify the search mode</h4>
260461
<p>xmake will automatically append the following configuration internally when it looks for cmake packages.</p>
261462
<pre><code class="lang-cmake">find_package(ABC CONFIG REQUIRED)
262463
</code></pre>
263-
<h4 id="stepbysteplocalpackagingtutorial">Step by Step Local Packaging Tutorial</h4>
264-
<p>In this tutorial we will package a static library called foo, upload it to a GitHub repository and consume it similar to a manner of CMake FetchContent</p>
265-
<ul>
266-
<li>Create an xmake project</li>
267-
</ul>
268-
<pre><code class="lang-bash">$ xmake create -P package_origin
269-
</code></pre>
270-
<ul>
271-
<li>Imitate this filetree to prepare files for your package</li>
272-
</ul>
273-
<pre><code class="lang-bash">│ .gitignore
274-
│ xmake.lua
275-
└───src
276-
│ main.cpp
277-
├───inc
278-
│ └───foo
279-
│ foo.hpp
280-
└───lib
281-
└───foo
282-
foo.cpp
283-
</code></pre>
284-
<ul>
285-
<li>Create static library target in xmake</li>
286-
</ul>
287-
<pre><code class="lang-lua">target("foo")
288-
set_kind("static")
289-
add_files("src/lib/foo/*.cpp")
290-
add_headerfiles("src/inc/foo/*.hpp")
291-
add_includedirs("src/inc/foo", {public = true})
292-
</code></pre>
293-
<ul>
294-
<li>Implement the functionality of your target</li>
295-
</ul>
296-
<p>foo.hpp</p>
297-
<pre><code class="lang-cpp">void foo();
298-
</code></pre>
299-
<p>foo.cpp</p>
300-
<pre><code class="lang-cpp">#include <iostream>
301-
#include "foo.hpp"
302-
303-
void foo() {
304-
std::cout << "foo";
305-
}
306-
</code></pre>
307-
<ul>
308-
<li>Build your project and create the package</li>
309-
</ul>
310-
<pre><code class="lang-bash">$ xmake build
311-
$ xmake package foo
312-
</code></pre>
313-
<ul>
314-
<li>Move packages artifacts to a custom package repository.</li>
315-
</ul>
316-
<pre><code class="lang-bash">$ mkdir xmake_local_package_tutorial
317-
$ cp -r build/packages xmake_local_package_tutorial/packages
318-
$ cd xmake_local_package_tutorial
319-
$ git init
320-
$ git add .
321-
$ git commit -a -m "init"
322-
</code></pre>
323-
<p>Then push this new package repository to your custom repository, e.g. <code>https://github.com/xxx/xmake_local_package_tutorial.git</code></p>
324-
<ul>
325-
<li>Create a project where you intend on consuming the package</li>
326-
</ul>
327-
<pre><code class="lang-bash">$ xmake create package_consumption
328-
</code></pre>
329-
<ul>
330-
<li>Consume the package by adding the repository, finding the package and then linking the package to target of your choosing</li>
331-
</ul>
332-
<pre><code class="lang-lua">add_repositories("foo https://github.com/xxx/xmake_local_package_tutorial.git")
333-
add_requires("foo")
334-
335-
target("package_consumption")
336-
set_kind("binary")
337-
add_files("src/*.cpp")
338-
add_packages("foo")
339-
</code></pre>
340-
<p>you can also use local repository.</p>
341-
<pre><code class="lang-lua">add_repositories("foo /localpath/xmake_local_package_tutorial")
342-
</code></pre>
343-
<pre><code class="lang-cpp">#include "foo.hpp"
344-
int main() {
345-
foo();
346-
return 0;
347-
}
348-
</code></pre>
349-
<p>Congratulations, you have packaged a library and consumed it xmake!</p>
350-
<pre><code class="lang-bash">$ xmake build
351-
$ xmake run
352-
foo
353-
</code></pre>
354464
</article>
355465
</body>
356466
</html>

0 commit comments

Comments
 (0)